水利智学系统 · 启动文件全面核查与优化清单

核查范围:start.bat / .env / requirements.txt / backend/main.py / frontend/index.html / watchdog.py / 项目根目录治理  |  方法:多维度列举法对比(现状 vs 应然) |  2026-09-27
目录: 总览 P0 严重问题 P1 重要问题 P2 一般优化 按文件逐条列举 推荐执行路线

一、总览仪表盘

7
P0 严重问题(立即修复)
14
P1 重要问题(本周修复)
18
P2 一般优化(迭代改进)
697
根目录文件总数
451
临时/补丁/诊断脚本(占65%)
13+
启动/重启入口文件(混乱)
50+
前端同步加载 script(首屏阻塞)
3处
版本号不一致(V4.0/V4.5.15/V4.5.17)

核查维度(144名专家视角映射为12个专业维度)

维度关注点发现问题数
🔒 安全专家密钥、CORS、鉴权、文件暴露、注入5
⚡ 性能工程师启动速度、首屏加载、缓存、并发、日志量6
🏗️ 架构师职责分离、模块化、重复代码、新旧并存5
🔧 DevOps启动流程、依赖管理、回滚、监控、优雅关闭6
🎨 前端专家资源加载、指纹、硬编码、主题、响应式7
🐍 后端专家单文件职责、中间件顺序、异常处理、数据库迁移6
🗄️ DBA连接池、迁移工具、索引、备份3
📋 可维护性版本一致、文档、临时文件、命名规范5
📊 可观测性日志策略、健康探针、指标、告警3
🌐 跨平台Windows/Linux、编码、路径、信号3
📱 移动端/PWASW、离线、meta、viewport3
🧹 项目治理根目录整洁、入口统一、备份策略4

二、P0 严重问题(立即修复)

P0-1 JWT 密钥为默认硬编码值
.env 中 JWT_SECRET=shuili_dev_secret_change_in_production,字面量提示"生产环境请修改"但从未修改
首次启动自动生成随机 64 位密钥写入 .env,或从环境变量注入;提供密钥轮换脚本
影响任何人拿到源码即可伪造任意用户 Token(含 admin),本地局域网使用时同网段设备可越权
修复start.bat 启动时检测 .env 中 JWT_SECRET 是否为默认值,若是则用 python -c "import secrets;print(secrets.token_hex(32))" 生成并写回
P0-2 /uploads 静态文件无鉴权直接暴露 + 手动路由与 StaticFiles 重复挂载
main.py L509 手动 @app.api_route("/uploads/{filename:path}") + L539 app.mount("/uploads", StaticFiles) 重复注册;上传的 PDF/视频/图片任何人可直接 URL 访问,无登录校验
删除手动路由(保留 StaticFiles 挂载),或对 /uploads 增加鉴权中间件(至少校验登录态);敏感文件走签名 URL
影响①重复挂载导致 StaticFiles 实际是死代码(手动路由先匹配);②上传的真题/讲义可被未登录用户下载;③手动路由 L515 打印完整磁盘路径到日志(信息泄露)
修复删除 L509-519 手动路由,统一用 StaticFiles;文件服务日志去掉完整路径,只打 filename
P0-3 前端 50+ 个 script 全部同步加载,无 defer,首屏严重阻塞
index.html L203-281 约 55 个 <script src="..."> 全部同步阻塞渲染,其中 pdfjs/d3/markmap 等第三方库体积大且非首屏必需
核心框架脚本加 defer;第三方库(pdfjs/markmap/flv)改为按需动态 import(用到时才加载);非关键模块延迟到 DOMContentLoaded 后
影响首屏白屏时间长(尤其平板/手机通过 Tailscale 访问时),50+ 个 JS 文件串行下载解析,用户感知"卡"
修复①所有业务 script 加 defer(保持执行顺序);②pdfjs/d3/markmap/flv 改为动态加载函数;③测量首屏 TTI 目标 <3s
P0-4 根目录被 451 个临时脚本淹没(占全部文件 65%)
项目根目录 697 个文件中 451 个是 add_*/fix_*/check_*/_temp_*/_patch_*/_probe_* 等一次性 Python 脚本,另有 22 张诊断截图、8 个诊断 JSON、12 个日志文件散落
临时脚本统一放入 tools/_archive/ 或 _temp_scripts/(已存在但未用);诊断产物放入 _diagnostics/;根目录只保留启动入口、配置、文档
影响①新用户/开发者无法快速找到真正的启动文件;②start.bat 的 cd /d "%~dp0" 后根目录杂乱影响排查;③临时脚本可能被误执行;④打包分发时体积膨胀
修复编写一次性归档脚本:将匹配 ^(add_|fix_|check_|_temp_|_patch_|_probe_|inspect_|verify_|test_|migrate_|retag_|restore_|revert_) 的 .py 移入 _archive/scripts/,_*.png 移入 _archive/screenshots/,_*.json 移入 _archive/reports/;根目录保留 start.bat/.env/requirements.txt/工作总控.md 等核心文件
P0-5 后端 main.py 自身 while-True 重启 + watchdog 外部监控 = 双重重启,可能循环杀进程
main.py L920 while True 包裹 uvicorn.run,崩溃后 5 秒自重启;同时 start.bat L240 启动 watchdog.py 独立监控进程存活+内存+端口,也会杀进程重启。两套重启机制无协调
二选一:要么 main.py 不做自重启(只跑一次 uvicorn,崩溃退出由 watchdog 拉起),要么不用 watchdog(main.py 自重启即可)。推荐保留 watchdog(功能更全:内存阈值、健康探针、端口检测),main.py 去掉 while True
影响①uvicorn 崩溃时 main.py 自重启 + watchdog 同时检测到"进程不响应"也杀进程重启,可能导致重复启动、端口冲突、日志混乱;②watchdog 内存超限杀进程时,main.py 的 while True 又立即拉起,可能陷入"启动→内存涨→被杀→再启动"循环
修复main.py 去掉 while True 循环,直接 uvicorn.run 一次;崩溃时退出码非零,由 watchdog 检测端口/健康后重启。watchdog 增加重启冷却(连续 N 次重启失败则告警停止)
P0-6 每次启动都 pip install 全部依赖,启动慢且依赖网络
start.bat L100 每次启动执行 pip install -r requirements.txt,即使依赖已安装也要重新解析、下载、检查,耗时 10-60 秒,网络不佳时直接启动失败
用依赖哈希校验:记录已安装依赖的 requirements.txt 哈希,若未变化则跳过 pip install;或用 pip install --dry-run 检测是否有缺失;首次安装后生成 .deps_installed 标记文件
影响①每次双击 start.bat 都要等 pip 检查,用户感知"启动慢";②网络不通时 pip 超时导致整个启动失败(即使依赖已装);③pip 可能意外升级依赖导致兼容性问题
修复start.bat 中:计算 requirements.txt 的哈希,与 backend/.deps_hash 对比,一致则跳过;不一致才 pip install 并更新哈希。同时 pip install --no-input --disable-pip-version-check 减少输出
P0-7 版本号三处不一致:start.bat 标题 V4.0 / 后端 FastAPI V4.5.15 / 前端 title V4.5.17
start.bat L3 title ShuiLi ZhiXue System V4.0;main.py L78 FastAPI(title="...V4.5.15", version="4.5.15");index.html L26 <title>...V4.5.17</title>;健康探针 L613 硬编码 "version": "v4.5.15"
单一事实源:在 core/build_meta.py 定义 VERSION 常量,main.py / index.html 模板注入 / start.bat 横幅均读取此常量;禁止任何文件硬编码版本号
影响用户报告 bug 时说的版本号与实际代码版本对不上,排查困难;浏览器标签页显示 V4.5.17 但 API 文档显示 V4.5.15,混乱
修复①core/build_meta.py 增加 VERSION = "4.5.17";②main.py 从 build_meta 导入;③index.html 的 title 由后端 root 路由动态替换(类似 ?v= 注入);④start.bat 标题改为读取版本或统一文字;⑤全局 grep 硬编码版本号并清除

三、P1 重要问题(本周修复)

P1-1 index.html 内联 style 硬编码 body 背景 #f5f7fa,又一个深色主题覆盖源
index.html L45 body { background: #f5f7fa; overflow: hidden; } 内联硬编码。虽然 framework.js 后加载用 var(--bg) 覆盖了它,但这是第三处 body 背景硬编码(此前 framework.js 已修),且若 framework.js 注入失败则深色主题完全失效
改为 body { background: var(--bg); color: var(--text); overflow: hidden; },所有颜色走 CSS 变量
影响深色主题的健壮性差,依赖 framework.js 必须成功注入;内联 style 中还有大量硬编码颜色(bootLoading 渐变 #1a237e/#3949ab、modal 背景 #fff 等),深色模式下这些元素不变色
修复①L45 body 背景改 var(--bg);②全局扫描 index.html 内联 style 中的硬编码颜色(#f5f7fa/#fff/#1a237e 等),替换为 CSS 变量或加 [data-theme=dark] 覆盖规则
P1-2 约 15 个前端 JS 文件无 ?v= 版本指纹,修改后浏览器不刷新
index.html 中以下 script 无 ?v= 指纹:event-bus.js、config.js、storage.js、music.js、sidebar.js、module-nav.js、photo-solve.js、knowledge_base.js、migration-plan.js、analytics.js、expert-center.js、memory.js、sprint.js 等。后端 root 路由的正则替换只给已有 ?v= 的加版本戳,无 ?v= 的不处理
所有 JS/CSS 引用统一加 ?v= 指纹;后端正则改为对所有 .js/.css 引用强制追加 ?v=APP_VERSION_TS(无论是否已有)
影响修改这些无指纹的 JS 后,用户浏览器缓存旧版本,bug "修复了但用户看不到",需手动强刷;移动端 SW 缓存更严重
修复①main.py L577 正则改为匹配所有 src/href 中的 .js/.css,无条件追加 ?v=APP_VERSION_TS;②index.html 中所有 script/link 统一格式
P1-3 启动流程串行执行 7+ 个 Python 子命令,每个重新 import,启动慢
start.bat L113-123 依次执行:preflight_check → mechanism_center.write_graph → monitor_subsystem → core.constitution → scripts/init_db,每个都是独立 python -c 子进程,每个都要重新 import FastAPI/SQLAlchemy 等(耗时 2-5 秒/个),总计 15-30 秒纯启动开销
合并为一个启动自检脚本 scripts/startup_check.py,一次 import 依次执行所有检查;或把这些检查移到 main.py 的 lifespan startup 事件中(后端启动时自动执行,不阻塞浏览器打开)
影响双击 start.bat 后要等 30+ 秒才能看到浏览器打开,用户感知"启动极慢";且 main.py __main__ 里又调用 init_db()(L849),与 start.bat 的 scripts/init_db.py 重复初始化
修复①start.bat 中 5 个 python -c 合并为一个 python scripts/startup_check.py;②去掉 start.bat 的 scripts/init_db.py(main.py 已调用 init_db);③目标:启动到浏览器打开 <10 秒
P1-4 启动入口混乱:13+ 个 bat/ps1/py 文件,用户不知该点哪个
根目录有:start.bat(主)、start.sh(Linux)、start_backend.bat、start_simple.bat、start_cosyvoice.bat、restart_backend.bat、restart_backend.ps1、一键启动.bat、一键启动.py、备份.bat、rollback_to_stable.bat、build_exe.bat、clean_restart.ps1。其中 start_simple.bat 仅 151 字节、一键启动.bat 仅 148 字节,可能是过时的简化版
统一为一个主入口 start.bat;其他入口要么删除(过时的),要么移入 tools/ 子目录(开发用的 restart/backup/build);在 README 中明确"双击 start.bat 即可"
影响用户可能误点 start_simple.bat(功能不全)或一键启动.bat(过时),导致启动异常;分发时用户困惑"这么多 bat 该点哪个"
修复①逐个检查每个启动文件的功能和时效性;②删除过时的 start_simple.bat/一键启动.bat(或合并到 start.bat);③restart/backup/build/rollback 移入 tools/;④根目录只留 start.bat + start.sh
P1-5 main.py 947 行单文件,职责过载(路由+中间件+静态+健康+缓存+启动+迁移+异常)
main.py 46KB / 947 行,包含:FastAPI 实例创建、日志配置、变更账本、4 个中间件、3 个异常处理器、请求日志、路由注册、PDF去水印API、uploads文件服务、LAN网关、静态挂载、版本注入、root路由、offline路由、健康探针、服务器时间、exam_config、favicon、init_db、_run_migrations(40+条硬编码迁移)、缓存中间件、__main__ 启动循环(while True + uvicorn + 信号处理)
按职责拆分:①core/app_factory.py(创建 FastAPI + 注册中间件/异常/路由);②core/lifespan.py(启动/关闭事件);③api/health.py(健康探针+服务器时间);④core/migrations.py(数据库迁移);⑤core/cache_middleware.py(缓存策略);main.py 只保留 from core.app_factory import create_app; app = create_app()
影响①修改任何功能都要在 947 行里找,易误改;②数据库迁移硬编码列表(L730+)越来越长,不可维护;③无法单独测试某个组件;④新开发者上手困难
修复分阶段拆分:第一阶段先把 _run_migrations 移到 core/migrations.py、健康探针移到 api/health.py、缓存中间件移到 core/cache_middleware.py;第二阶段引入 lifespan 替代 __main__ 里的启动逻辑
P1-6 数据库迁移用硬编码列表,无版本化迁移工具
main.py L713-749+ _run_migrations() 用硬编码 Python 列表定义 40+ 条 ALTER TABLE 迁移,每条是 (version, table, column, ddl) 元组,通过 PRAGMA table_info 检查列是否存在来决定是否执行。没有 down 迁移、没有事务外的回滚、迁移记录和代码混在一起
引入 Alembic(SQLAlchemy 官方迁移工具),每个迁移一个文件,支持 upgrade/downgrade,迁移历史版本化;或至少把迁移列表移到独立文件 migrations/ 目录
影响①迁移列表越来越长(已 40+ 条),main.py 臃肿;②无法回滚错误的迁移;③新迁移需要在 main.py 里加元组,容易出错;④没有迁移审计
修复①短期:把 _run_migrations 移到 core/migrations.py,迁移列表移到 migrations/versions.py;②长期:引入 Alembic,编写初始基线(当前 schema),后续迁移用 Alembic
P1-7 每个请求打 2 条 INFO 日志(开始+完成),高并发下日志爆炸
main.py L476-485 log_requests 中间件对每个请求打 请求开始: GET /api/... 和 请求完成: GET /api/... -> 200 两条 INFO。加上 uvicorn 自身的 access log,每个请求至少 3 条日志。静态资源请求(/static/*.js)也打日志
①只打完成日志(含耗时),不打开始日志;②静态资源请求(/static/、/uploads/)跳过日志;③日志级别改为 DEBUG(生产用 INFO 只打慢请求/错误);④增加请求耗时字段
影响①backend/data/logs/app.log 快速增长(RotatingFileHandler 10MB×7=70MB 上限但仍大);②日志噪音淹没真正的错误;③磁盘 IO 开销
修复①log_requests 去掉"请求开始"日志,只保留"请求完成"并增加耗时;②对 path.startswith('/static/') or '/uploads/' or '/favicon' 的请求跳过日志;③uvicorn log_level 改为 warning(access log 关掉)
P1-8 无优雅关闭脚本(stop.bat),关闭 start.bat 窗口后 WMI 后端进程残留
start.bat L202 用 WMI 启动后端(Invoke-WmiMethod Win32_Process Create),后端进程脱离 cmd 窗口。关闭 start.bat 窗口只停 watchdog(L240 前台运行),WMI 启动的 python main.py 进程继续运行占用 8000 端口。用户想"完全关闭"时只能 taskkill /F /IM python.exe(会误杀其他 Python 进程)
提供 stop.bat:①读取后端 PID(写入 backend/data/backend.pid);②发送优雅关闭信号(或调用 /api/shutdown 端点);③等待 30 秒后强制 kill;④同时停 watchdog、auto_backup、watch 等附属进程
影响①用户关闭窗口后以为系统停了,实际后端还在跑(占用内存/端口);②再次 start.bat 时杀 8000 端口进程(L32-35)可能误杀;③没有 PID 文件,无法精确定位后端进程
修复①main.py 启动时写 PID 到 backend/data/backend.pid;②新增 stop.bat 读 PID 优雅关闭;③start.bat 横幅提示"关闭窗口只停看门狗,完全关闭请运行 stop.bat";④增加 /api/admin/shutdown 端点(需 admin 鉴权)
P1-9 meta 标签无效:theme-color 用 CSS 变量、Cache-Control 与后端矛盾
index.html L24 <meta name="theme-color" content="var(--primary)"> —— meta 标签不支持 CSS 变量,浏览器忽略,移动端浏览器地址栏颜色不变;L25 <meta http-equiv="Cache-Control" content="max-age=3600"> —— 后端 root 路由已发 Cache-Control: no-store 响应头,meta 被覆盖且矛盾
①theme-color 用固定颜色(如 #1e293b)或用 JS 动态设置 document.querySelector('meta[name=theme-color]').content = getComputedStyle(document.documentElement).getPropertyValue('--primary');②删除 L25 的 Cache-Control meta(后端响应头已控制)
影响移动端浏览器地址栏不跟随主题色;HTML 缓存策略混乱(meta 说缓存 1 小时,响应头说不缓存)
修复①删除 L25;②L24 theme-color 改固定值 + theme.js applyTheme 中动态更新 meta theme-color
P1-10 requirements.txt 版本约束宽松 + PyPDF2/pypdf 重复 + 无锁定文件
所有依赖用 >= 约束(如 fastapi>=0.100.0),不可复现构建;PyPDF2>=3.0.0 和 pypdf>=4.0.0 同时存在(PyPDF2 已废弃,pypdf 是其继任者,功能重复);无 requirements.lock / poetry.lock / Pipfile.lock
①删除 PyPDF2(统一用 pypdf),检查代码中 import PyPDF2 的地方改为 pypdf;②生成 requirements.lock(pip freeze)用于可复现构建;③核心依赖用 == 锁定版本
影响①不同时间安装得到不同版本,可能引入不兼容变更(如 fastapi 0.110 改了某些行为);②PyPDF2 和 pypdf 同时安装占空间且可能 import 冲突;③无法追溯"哪个版本导致的 bug"
修复①grep 代码中 import PyPDF2 / from PyPDF2,改为 pypdf;②删除 requirements.txt 中的 PyPDF2;③生成 requirements.lock 并在 start.bat 中优先用 lock 文件安装
P1-11 watchdog 内存阈值 800MB 与 start.bat 横幅 600MB 不一致
watchdog.py L41 MEMORY_LIMIT_MB = 800;start.bat L228 横幅写 memory ^<600MB。两处阈值不一致,用户看到的提示与实际行为不符
阈值单一事实源:在 watchdog.py 顶部定义常量,start.bat 不写具体数字(或读取同一配置);实际阈值建议 1024MB(PDF 解析/OCR 有瞬时峰值)
影响用户以为 600MB 就会重启,实际 800MB 才重启;PDF 批量解析时内存可能涨到 1.5GB 不被重启(如果阈值是 800 但连续超限才重启,有 MEM_STRIKE_LIMIT 缓冲)
修复①统一阈值为 1024MB(或根据实际内存峰值调整);②start.bat 横幅改为 memory <%MEMORY_LIMIT%%MB 从配置读取或删除具体数字
P1-12 CORS 配置 allow_credentials=False 但 allow_methods/headers=["*"],本地使用过松
main.py L415-421 CORS 配置 allow_origins=CORS_ORIGINS, allow_credentials=False, allow_methods=["*"], allow_headers=["*"]。需确认 CORS_ORIGINS 的值(core/config.py),如果是 ["*"] 则任意网站可调用 API
本地使用场景下 CORS 可宽松,但应明确白名单(localhost:8000、127.0.0.1:8000、Tailscale IP、LAN IP),而非 *;allow_credentials 与 allow_origins=["*"] 不能同时为 True(浏览器限制),当前 False 是对的
影响如果 CORS_ORIGINS 是 ["*"],则任意恶意网页可在用户浏览器中调用本地 API(如 /api/users、/api/questions),结合 JWT 默认密钥风险更大
修复①检查 core/config.py 中 CORS_ORIGINS 的值;②改为明确白名单:["http://localhost:8000","http://127.0.0.1:8000","http://100.81.103.0:8000"] + 动态 LAN IP;③增加 /api/admin/* 路径的 CORS 限制
P1-13 旧代码 app_v3_897262.js(300KB+)与模块化代码并存,双重加载
index.html L251 完整加载 app_v3_897262.js(旧版单体应用,300KB+),同时 L211-281 加载 30+ 个模块化 JS。旧代码作为"代理壳转发"存在,但实际很多功能已迁移到模块化,旧代码中大量函数是死代码
制定迁移完成标准:逐个功能确认模块化版本可用后,从 app_v3 中删除对应代码;最终目标是完全移除 app_v3,只保留模块化代码;短期可将 app_v3 改为按需加载(只在用到未迁移功能时才加载)
影响①首屏多下载 300KB+ JS(移动端 Tailscale 下尤其慢);②新旧代码可能有函数名冲突/覆盖,导致难以排查的 bug;③维护成本翻倍(改一个功能要改两处)
修复①生成 app_v3 函数使用清单(哪些函数被模块化代码调用);②只保留被引用的函数,删除死代码;③长期目标:完全移除 app_v3
P1-14 全局异常处理器捕获所有 Exception,可能掩盖 bug
main.py L168 @app.exception_handler(Exception) 捕获所有未处理异常,返回统一 JSON。这会把编程错误(如 AttributeError、KeyError、TypeError)也包装成 500 JSON,堆栈信息只在日志里,开发时难以快速定位
区分处理:①HTTPException 走 http_exception_handler;②RequestValidationError 走 validation;③其他 Exception 记录完整堆栈到日志 + 返回 500,但在开发模式(DEBUG=True)下返回堆栈信息到响应体便于调试;④增加 Sentry/错误上报
影响①生产环境下用户看到"服务器内部错误"但开发者需翻日志才知道具体原因;②某些异常被静默吞掉(except Exception: pass 在多处出现),导致"功能没反应但没报错"
修复①全局异常处理器增加 request_id 关联日志;②DEBUG 模式下返回堆栈;③全局扫描 except Exception: pass,至少改为 except Exception as e: logger.warning(...)

四、P2 一般优化(迭代改进)

P2-1 start.bat 杀 8000 端口用 netstat|findstr,可能误杀虚拟网卡/其他服务
现状L32 netstat -ano | findstr ":8000" | findstr LISTENING 取第 5 个 token 作为 PID。如果 netstat 输出格式变化(如 IPv6 地址含多个冒号),token 位置可能错
建议改用 PowerShell Get-NetTCPConnection -LocalPort 8000 -State Listen 精确获取 OwningProcess,或用 Python psutil(已在 requirements 中)
P2-2 LAN IP 检测取第一个 IPv4,可能是虚拟网卡(Tailscale/WSL/VirtualBox)
现状L137 ipconfig | findstr /i "IPv4" 取第一个,可能是 Tailscale 的 100.x 或 WSL 的 172.x,而非真实局域网 IP
建议用 Python psutil.net_if_addrs() 过滤物理网卡(排除 Tailscale、WSL、VirtualBox、VMware),取 192.168.x.x / 10.x.x.x 优先级;或直接用 Tailscale IP 作为统一地址(已实现)
P2-3 .env 中 DB_PATH/UPLOAD_DIR 为相对路径,依赖工作目录
现状DB_PATH=backend/data/shuili_exam.db、UPLOAD_DIR=uploads,如果从非项目根目录启动(如 cd backend && python main.py),路径解析错误
建议core/config.py 中对相对路径统一做 os.path.join(BASE_DIR, path) 绝对化;或 .env 中用绝对路径
P2-4 无 .env.example,新部署不知需配置哪些环境变量
现状只有 .env(含实际值),没有 .env.example 模板
建议创建 .env.example,列出所有可配置变量及说明(AI_PROVIDER、AI_API_URL、AI_MODEL、PORT、DB_PATH、JWT_SECRET、UPLOAD_DIR、CORS_ORIGINS、DEBUG 等)
P2-5 index.html 内联 style 约 130 行硬编码样式,应抽到 CSS 文件
现状L36-185 内联 <style> 包含 bootLoading、sidebar 宽度、响应式、loading-spinner、empty-state、tool-dock-right 等样式,与外部 CSS(tokens.css/components.css/style.min.css/common.css/mobile-shell.css)职责重叠
建议将内联样式抽到 css/boot.css(启动加载样式)和 css/layout-overrides.css(布局覆盖),index.html 只保留最关键的防闪烁样式(如 body 背景、sidebar 宽度)
P2-6 大量 !important 覆盖(sidebar 宽度 135px、main-content margin-left)
现状index.html L46-47 .sidebar { width: 135px !important; min-width: 135px !important; max-width: 135px !important; }、.main-content { margin-left: 135px !important; },用 !important 强制覆盖外部 CSS
建议①侧边栏宽度定义为 CSS 变量 --sidebar-width: 135px;②外部 CSS 中使用变量而非硬编码;③去掉 !important,靠 CSS 优先级(后加载的覆盖先加载的)
P2-7 无 noscript 标签,JS 禁用时白屏
现状index.html 无 <noscript>,JS 被禁用时页面空白
建议增加 <noscript><div style="...">本系统需要启用 JavaScript 才能运行</div></noscript>
P2-8 无关键资源 preload/preconnect,首屏优化空间
现状index.html 无 <link rel="preload"> / <link rel="preconnect">,关键 CSS/JS 等到解析到才下载
建议①对 tokens.css/components.css 加 preload;②对核心 JS(framework.js/theme.js/data-service.js)加 preload;③对后端 API 加 preconnect(<link rel="preconnect" href="http://localhost:8000">)
P2-9 SQLite 无连接池配置,单连接并发瓶颈
现状core/db.py 用 SQLAlchemy + aiosqlite,未显式配置连接池大小(SQLite 默认单连接),并发写入时可能锁库
建议①配置 pool_size=5, max_overflow=10(SQLite 支持但有限);②写操作加 WAL 模式(PRAGMA journal_mode=WAL)提高并发读;③长期考虑 PostgreSQL(如果用户量增长)
P2-10 日志文件散落多处:backend/data/logs/ + 根目录 .log + backend/*.log
现状日志分布在:backend/data/logs/app.log(RotatingFileHandler)、根目录 backend_startup.log(137KB)、backend/server.out.log(257KB)、backend/be3_out.log(2.6MB)、backend/_out.log(258KB)、根目录 _rag_rebuild.log(85KB) 等
建议①统一日志目录 logs/(项目根或 backend/data/logs);②start.bat 中后端 stdout/stderr 重定向到 logs/backend.out.log 和 logs/backend.err.log;③定期清理旧日志(已有 _cleanup_old_logs 但只清 app.log)
P2-11 备份文件 .bak_* 散落在代码目录,应统一到 backups/
现状backend/main.py.bak_20260918_002427 等 4 个备份、backend/watchdog.py.bak_*、根目录 auto_backup.py.bak_* 散落在代码旁
建议①所有 .bak_* 文件移入 backups/ 目录(按日期子目录);②. gitignore 中忽略 *.bak_*;③定期清理 30 天前的备份
P2-12 uvicorn workers=1 单进程,无法利用多核
现状main.py L933 workers=1,单进程单事件循环
建议本地单机使用场景下单进程足够(用户量小),但如果需要更高并发可改为 workers=2(注意 SQLite 多进程写入限制);当前保持 1 即可,标注为"已知限制"
P2-13 RateLimit 120次/分钟硬编码,本地使用可能过严(视频播放/轮询)
现状main.py L443 max_requests=120, window_seconds=60,视频播放时前端可能频繁请求(进度保存、心跳),120次/分钟可能触发限流
建议①提高到 300次/分钟(本地使用无恶意流量);②白名单路径(/static/、/uploads/、/api/health)不限流;③限流响应返回 Retry-After 头
P2-14 无 README.md(或不显眼),新用户不知如何启动/配置/故障排查
现状根目录有大量 .md 文档(工作总控.md 349KB、架构总控文件.md 1.6MB、系统交付级诊断报告.md 等),但没有简洁的 README.md 告诉用户"双击 start.bat 即可"
建议创建 README.md:①系统简介;②快速启动(双击 start.bat);③默认账号;④统一访问地址;⑤常见问题(端口占用、Python 版本、平板访问);⑥目录结构说明
P2-15 start.bat 中 chcp 65001 后中文输出在某些 Windows 版本仍可能乱码
现状L2 chcp 65001 >nul 切换到 UTF-8,但 cmd 窗口字体可能不支持中文(如默认点阵字体),且 Python 子进程输出在 GBK 控制台可能乱码
建议①start.bat 中 set PYTHONIOENCODING=utf-8(已有 -X utf8 参数);②关键提示用英文+中文双语;③考虑用 Python 启动脚本替代 bat(一键启动.py 已存在但只有 3.7KB)
P2-16 静态资源缓存策略:电脑本地 http 访问时 JS/CSS 设为 no-store,每次刷新全量下载
现状main.py L832-835 非移动端(http)时 JS/CSS 设为 no-store,理由是"改完普通刷新即生效"。但 50+ 个 JS 文件每次刷新都重新下载,即使内容没变(有 ?v= 指纹)
建议带 ?v= 指纹的 JS/CSS 应设为 max-age=3600(1小时),因为指纹变了 URL 就变了,不会缓存旧版本;不带指纹的才 no-store。这样二次打开秒开,改代码后指纹变了自动拉新
P2-17 健康探针中数据库路径硬编码,与 config 不一致
现状main.py L616 db_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data', 'shuili_exam.db') 硬编码,而 .env 中 DB_PATH 可配置
建议从 core.config 导入 DB_PATH,不硬编码
P2-18 无启动耗时统计,无法量化优化效果
现状start.bat 各阶段没有时间戳,无法知道"pip install 花了多久""init_db 花了多久"
建议start.bat 中各阶段加 echo [%time%] ...,最后输出总耗时;main.py 启动时记录 startup_duration 到日志

五、按文件逐条列举(速查表)

start.bat(9319B / 251行)

#行号问题优先级
1L3标题 V4.0,与实际 V4.5.17 不一致P0
2L32-35杀 8000 端口用 netstat|findstr,可能误杀P2
3L100每次启动 pip install,慢且依赖网络P0
4L113-1235个 python -c 串行执行,启动慢P1
5L123scripts/init_db.py 与 main.py init_db() 重复P1
6L137LAN IP 取第一个 IPv4,可能是虚拟网卡P2
7L149Tailscale 路径硬编码 C:\Program Files\TailscaleP2
8L202WMI 启动后端,关闭窗口后进程残留P1
9L228横幅 memory<600MB 与 watchdog 800MB 不一致P1
10全局无 stop.bat,无优雅关闭P1
11全局无启动耗时统计P2

backend/main.py(46792B / 947行)

#行号问题优先级
1L78FastAPI title V4.5.15,与前端 V4.5.17 不一致P0
2L168全局 Exception 处理器,可能掩盖 bugP1
3L476-485每请求 2 条 INFO 日志,静态资源也打P1
4L509-519/uploads 手动路由,与 L539 StaticFiles 重复挂载P0
5L515文件服务日志打印完整磁盘路径(信息泄露)P0
6L577版本注入正则只处理已有 ?v= 的,无指纹的 JS 不处理P1
7L613健康探针 version 硬编码 v4.5.15P0
8L616健康探针 DB 路径硬编码P2
9L713-749+数据库迁移硬编码列表,无版本化工具P1
10L832-835http 访问时带指纹 JS/CSS 也 no-store,浪费带宽P2
11L920-945while True 自重启,与 watchdog 双重重启P0
12L933workers=1 单进程P2
13L947文件 947 行职责过载,应拆分P1
14L415-421CORS 配置需确认 CORS_ORIGINS 值P1
15L443RateLimit 120次/分可能过严P2

frontend/index.html(28636B)

#行号问题优先级
1L24meta theme-color 用 CSS 变量,无效P1
2L25meta Cache-Control 与后端 no-store 矛盾P1
3L26title V4.5.17,与后端 V4.5.15 不一致P0
4L45body 背景硬编码 #f5f7fa,深色主题覆盖源P1
5L46-47sidebar 宽度大量 !importantP2
6L36-185内联 style 130 行,应抽到 CSS 文件P2
7L203-207第三方库(pdfjs/d3/markmap)同步阻塞,无 deferP0
8L211-28150+ script 全部同步加载,无 deferP0
9多个约 15 个 JS 无 ?v= 指纹P1
10L251app_v3_897262.js 300KB+ 与模块化并存P1
11全局无 noscriptP2
12全局无 preload/preconnectP2

.env / requirements.txt / watchdog.py / 项目治理

文件#问题优先级
.env1JWT_SECRET 默认硬编码值P0
.env2DB_PATH/UPLOAD_DIR 相对路径P2
.env3无 .env.exampleP2
requirements1版本约束宽松(>=),不可复现P1
requirements2PyPDF2 + pypdf 重复P1
requirements3无锁定文件P1
watchdog1内存阈值 800MB 与横幅 600MB 不一致P1
watchdog2与 main.py 自重启双重重启P0
项目治理1根目录 451 个临时脚本(占65%)P0
项目治理213+ 个启动入口文件混乱P1
项目治理3日志散落多处P2
项目治理4.bak_* 备份散落代码目录P2
项目治理5无 README.mdP2

六、推荐执行路线(分4阶段)

阶段一:紧急止血(1-2天,7项 P0)

①JWT 密钥自动生成   ②删除 /uploads 重复挂载+日志去路径   ③前端 script 加 defer   ④根目录临时脚本归档   ⑤去掉 main.py while True 自重启(保留 watchdog)   ⑥pip install 哈希跳过   ⑦版本号统一单一事实源

阶段二:体验优化(3-5天,14项 P1)

①index.html body 背景改 CSS 变量   ②所有 JS 统一加 ?v= 指纹   ③启动自检合并为一个脚本   ④启动入口统一   ⑤main.py 拆分(迁移/健康/缓存移出)   ⑥数据库迁移独立文件   ⑦日志降噪   ⑧stop.bat 优雅关闭   ⑨meta 标签修复   ⑩PyPDF2 移除   ⑪watchdog 阈值统一   ⑫CORS 白名单   ⑬app_v3 瘦身   ⑭异常处理器增强

阶段三:精耕细作(1-2周,18项 P2)

端口检测改用 PowerShell/psutil、LAN IP 过滤虚拟网卡、相对路径绝对化、.env.example、内联样式抽 CSS、!important 清理、noscript、preload、SQLite WAL、日志统一目录、备份归档、RateLimit 调优、README、启动耗时统计、带指纹资源缓存策略、健康探针 DB 路径配置化等

阶段四:长期演进(持续)

①引入 Alembic 数据库迁移   ②完全移除 app_v3 旧代码   ③前端 ES Modules + 动态 import   ④后端模块化拆分(api/、core/、services/)   ⑤自动化测试 + CI   ⑥错误上报(Sentry 替代)   ⑦考虑 PostgreSQL(用户量增长时)

预期收益

指标当前阶段一后阶段二后
启动到浏览器打开30-60秒15-20秒<10秒
首屏可交互(TTI)5-10秒(平板)3-5秒<3秒
根目录文件数697~250~100
前端 JS 请求数55+55+(但 defer 不阻塞)~40(按需加载)
版本号一致性3处不同统一统一
深色主题健壮性依赖 framework.js 注入—全变量化,无硬编码