580 lines
15 KiB
Markdown
580 lines
15 KiB
Markdown
# llm-in-text 生产环境修复清单
|
||
|
||
## 文档目的
|
||
|
||
本文档是针对当前仓库在 2026-04-01 状态下基于代码的生产就绪性审查。
|
||
|
||
它回答三个问题：
|
||
|
||
1. 当前项目是否已准备好投入生产？
|
||
2. 自上次审查以来已修复了哪些问题？
|
||
3. 还有什么因素阻碍安全上线？
|
||
|
||
本次审查仅限于仓库中已有的内容和本地直接验证的内容，不包括外部基础设施、反向代理配置、云资源、CI 平台密钥或运行时运维的完整审计。
|
||
|
||
## 审查范围
|
||
|
||
- 前端构建和运行时入口
|
||
- 后端 FastAPI 端点和模型集成
|
||
- 补全、OCR 和文件转换请求路径
|
||
- 隐私相关行为和本地存储
|
||
- 基础测试覆盖率和构建验证
|
||
- PWA/Service Worker 状态
|
||
- 仓库中存在的部署和运维工件
|
||
|
||
## 已验证的事实
|
||
|
||
以下项目已针对当前仓库直接验证：
|
||
|
||
- 前端生产构建通过 `npm.cmd run build` 成功
|
||
- 后端测试通过 `pytest backend/tests -q`
|
||
- 当前后端测试结果：`8 passed, 1 skipped`
|
||
- 存在健康检查端点：`/health/live` 和 `/health/ready`
|
||
- 前端不再硬编码 API 密钥
|
||
- 后端不再需要旧的 `X-API-Key` 头
|
||
- 前端隐私模式现在默认为启用
|
||
- 后端错误响应现在已规范化，不再返回原始异常字符串
|
||
- OCR 和转换端点现在强制执行基本的文件大小和扩展名检查
|
||
|
||
## 当前评估
|
||
|
||
项目尚未准备好投入生产。
|
||
|
||
当前状态更接近于：
|
||
|
||
- 一个可用的原型
|
||
- 内部演示
|
||
- 具有部分加固的预发布候选版本
|
||
|
||
由于缺少几个核心生产基线，它尚未准备好面向互联网的生产使用：
|
||
|
||
- 真正的限流和并发保护
|
||
- 正式的部署工件和运行时拓扑
|
||
- CI/CD 和自动化质量门禁
|
||
- 结构化的可观测性和告警
|
||
- 更强的请求验证和更安全的文件处理隔离
|
||
- 前端自动化测试和端到端验证
|
||
|
||
## 已修复的问题
|
||
|
||
与之前的清单相比，以下项目不再作为阻碍因素：
|
||
|
||
### 已修复：硬编码的前端/后端共享 API 密钥
|
||
|
||
- `src/utils/api.js` 不再发送 `X-API-Key`
|
||
- `src/utils/convert.js` 不再发送 `X-API-Key`
|
||
- `backend/main.py` 不再强制执行旧的静态密钥
|
||
|
||
这消除了上次审查中最严重的问题之一。
|
||
|
||
遗留问题：
|
||
|
||
- `backend/tests/test_main_cancel.py` 仍然包含过时的 `X-API-Key` 头，但它们目前是无效的，表明测试假设已过时而非活动中的认证逻辑
|
||
|
||
### 已修复：危险的通配符 CORS 配置
|
||
|
||
当前后端 CORS 限制为：
|
||
|
||
- `http://localhost:5173`
|
||
- `http://localhost:3000`
|
||
|
||
并使用：
|
||
|
||
- `allow_credentials=False`
|
||
- `allow_methods=["POST", "OPTIONS"]`
|
||
- `allow_headers=["Content-Type", "X-Request-Id"]`
|
||
|
||
这比之前的通配符配置安全得多。
|
||
|
||
遗留问题：
|
||
|
||
- CORS 仍然针对本地开发硬编码，对于 staging/生产环境不是环境驱动的
|
||
|
||
### 已修复：默认收集前端公网 IP
|
||
|
||
- `src/stores/settings.js` 现在将 `privacyMode` 默认为 `true`
|
||
- `src/utils/api.js` 不再调用 `ipify`
|
||
- `src/utils/api.js` 不再发送 `X-Client-IP`
|
||
- `backend/main.py` 不再将 IP 派生的位置注入提示词
|
||
|
||
遗留问题：
|
||
|
||
- `backend/geoip.py` 和 GeoLite 数据库仍然存在于仓库中，这可能会造成对当前隐私模型的混淆
|
||
|
||
### 已修复：向客户端暴露原始异常字符串
|
||
|
||
当前后端响应使用 `_error_response(...)` 和结构化载荷，例如：
|
||
|
||
- `INTERNAL_ERROR`
|
||
- `OCR_FAILED`
|
||
- `CONVERT_FAILED`
|
||
- `FILE_TOO_LARGE`
|
||
- `INVALID_FILE_TYPE`
|
||
|
||
这比直接返回 `str(exception)` 更好。
|
||
|
||
遗留问题：
|
||
|
||
- 日志仍然记录用户派生内容的预览，这是另一个隐私/可观测性问题
|
||
|
||
### 部分修复：上传和转换输入边界
|
||
|
||
`backend/main.py` 中的当前后端保护包括：
|
||
|
||
- OCR 大小上限：10 MB
|
||
- 转换大小上限：50 MB
|
||
- OCR 和转换的扩展名白名单
|
||
- 在 `finally` 中清理临时转换文件
|
||
|
||
这是有意义的进展，但不足以投入生产。
|
||
|
||
## 生产阻碍因素
|
||
|
||
优先级含义：
|
||
|
||
- `P0`：必须在生产上线前完成
|
||
- `P1`：应在公开发布或广泛推广前完成
|
||
- `P2`：重要的后续加固和维护工作
|
||
|
||
---
|
||
|
||
## P0 阻碍因素
|
||
|
||
### P0-01 声明了限流和并发控制但未强制执行
|
||
|
||
当前状态：
|
||
|
||
- `backend/main.py` 定义了 `MAX_CONCURRENT_COMPLETIONS = 4`
|
||
- `backend/main.py` 定义了 `COMPLETION_RATE_LIMIT = 60`
|
||
- 没有任何实际的限流器使用这两个值
|
||
- OCR 和转换端点也没有真正的每客户端节流
|
||
|
||
风险：
|
||
|
||
- 容易滥用昂贵的补全/OCR/转换端点
|
||
- 可避免地对模型主机、CPU、内存和临时存储造成过载
|
||
- 突发流量下无法控制降级
|
||
|
||
必需的修复：
|
||
|
||
1. 在应用或网关中强制执行真正的每路由限流
|
||
2. 为补全作业添加真正的并发保护
|
||
3. 为 `/v1/completions`、`/v1/ocr`、`/v1/convert` 添加单独预算
|
||
4. 达到限制时返回明确的 `429`
|
||
5. 为节流的请求和队列深度发出指标
|
||
|
||
验收标准：
|
||
|
||
- 重复的突发流量触发确定性的 `429`
|
||
- 并发补全不能超过配置的预算
|
||
- 负载测试下服务保持稳定
|
||
|
||
---
|
||
|
||
### P0-02 仓库中不存在生产部署基线
|
||
|
||
当前状态：
|
||
|
||
- 后端仅通过 `uvicorn.run(...)` 暴露开发式启动
|
||
- 没有 `Dockerfile`
|
||
- 没有 compose 文件
|
||
- 没有 Kubernetes 清单或 Helm chart
|
||
- 没有 systemd 单元
|
||
- 没有反向代理参考配置
|
||
- 没有记录的生产环境契约
|
||
|
||
风险：
|
||
|
||
- 没有可复现的部署路径
|
||
- 没有明确的过程监督、重启或优雅的发布模型
|
||
- 没有记录的 ingress/请求体大小/超时/TLS 姿态
|
||
|
||
必需的修复：
|
||
|
||
1. 定义一个官方部署目标
|
||
2. 为该目标添加部署工件
|
||
3. 记录所需的环境变量、端口、探针和存储
|
||
4. 定义优雅关闭和发布行为
|
||
5. 记录反向代理限制和信任边界
|
||
|
||
验收标准：
|
||
|
||
- 新环境可以从仓库文档和工件部署
|
||
- 健康探针已接入所选运行时
|
||
- 回滚路径已记录
|
||
|
||
---
|
||
|
||
### P0-03 缺少 CI/CD 和仓库质量门禁
|
||
|
||
当前状态：
|
||
|
||
- 仓库级别没有找到 `.github/workflows`
|
||
- `package.json` 没有真正的前端测试脚本
|
||
- 没有 lint 脚本
|
||
- 没有类型检查脚本
|
||
- 没有依赖扫描或密钥扫描工作流
|
||
|
||
风险：
|
||
|
||
- 回归只能手动捕获
|
||
- 安全和打包漂移很可能发生
|
||
- 生产就绪性取决于本地开发者的规范
|
||
|
||
必需的修复：
|
||
|
||
1. 为构建和测试添加 CI 工作流
|
||
2. 添加前端自动化测试
|
||
3. 在适用的情况下添加 lint 和类型检查门禁
|
||
4. 添加依赖漏洞扫描
|
||
5. 添加密钥扫描和基本 SAST
|
||
|
||
验收标准：
|
||
|
||
- 每个 PR 都运行构建、后端测试、前端测试和 lint
|
||
- 失败的检查阻止合并
|
||
|
||
---
|
||
|
||
### P0-04 文件处理路径仍然缺乏生产级隔离
|
||
|
||
当前状态：
|
||
|
||
- 后端将完整 base64 载荷解码到内存中
|
||
- 转换写入临时文件并将其传递给 `markitdown`
|
||
- OCR 和转换主要依赖扩展名检查，而不是内容嗅探
|
||
- 没有工作进程隔离或用于转换的单独沙箱
|
||
- 转换任务没有队列或资源预算
|
||
|
||
风险：
|
||
|
||
- 大型或并发上传导致内存峰值
|
||
- 畸形或对抗性文档会给解析器带来压力
|
||
- 转换工作负载可能干扰核心补全可用性
|
||
|
||
必需的修复：
|
||
|
||
1. 明确验证 base64 解码失败
|
||
2. 添加 MIME/内容嗅探，而不仅仅是扩展名检查
|
||
3. 在入口和应用层添加更低的、路由特定的请求体限制
|
||
4. 将转换隔离到单独的工作进程/进程边界
|
||
5. 添加超时、并发上限和队列深度控制
|
||
|
||
验收标准：
|
||
|
||
- 畸形载荷失败并返回明确的 4xx 响应
|
||
- 转换不能饿死补全服务
|
||
- 压力下临时文件和内存增长保持有界
|
||
|
||
---
|
||
|
||
### P0-05 环境配置不一致且不安全
|
||
|
||
当前状态：
|
||
|
||
- 前端 `.env.example` 相当安全
|
||
- 后端 `.env.example` 过时且与代码不一致
|
||
- 代码读取 `OLLAMA_HOST`
|
||
- 后端示例仍然使用 `OLLAMA_BASE_URL`
|
||
- 后端示例仍然定义 `OPENAI_API_KEY=ollama`，这是误导性的
|
||
|
||
风险：
|
||
|
||
- 新环境配置不正确
|
||
- 运营商可能假设不支持的认证/配置行为
|
||
- staging/生产漂移很可能发生
|
||
|
||
必需的修复：
|
||
|
||
1. 用代码实际使用的变量替换后端环境示例
|
||
2. 在启动时验证所需的环境变量
|
||
3. 分离开发、staging 和生产环境契约
|
||
4. 缺失关键配置时快速失败
|
||
|
||
验收标准：
|
||
|
||
- 示例环境文件匹配真实运行时行为
|
||
- 无效或缺失关键配置导致启动失败
|
||
|
||
---
|
||
|
||
## P1 高优先级差距
|
||
|
||
### P1-01 日志仍然捕获用户派生内容预览
|
||
|
||
当前状态：
|
||
|
||
- `backend/main.py` 记录提示词派生的前缀和后缀预览
|
||
- 补全结果记录包含内容预览
|
||
- OCR 和转换记录文本预览长度和片段
|
||
|
||
风险：
|
||
|
||
- 日志可能包含敏感文档内容
|
||
- 隐私姿态与应用可见的隐私设置不一致
|
||
- 难以证明保留/合规姿态
|
||
|
||
必需的修复：
|
||
|
||
1. 默认情况下停止记录用户内容正文和预览
|
||
2. 仅保留请求元数据：路由、请求 ID、状态、延迟、大小
|
||
3. 引入结构化 JSON 日志
|
||
4. 脱敏或哈希任何敏感标识符
|
||
|
||
验收标准：
|
||
|
||
- 默认日志不包含用户文档文本
|
||
- 请求关联仍可通过请求 ID 和元数据工作
|
||
|
||
### P1-02 请求验证仍然过于宽松
|
||
|
||
当前状态：
|
||
|
||
- Pydantic 模型定义了字段但没有长度或枚举约束
|
||
- `prefix`、`suffix`、`filename` 和 `reason` 受到极小约束
|
||
- base64 字段在路由特定检查之前仍然可能非常大
|
||
- 前端转换路径在将完整文件读入 base64 之前不执行预验证
|
||
|
||
风险：
|
||
|
||
- 过大或畸形的请求太容易到达昂贵的逻辑
|
||
- 端点之间的 4xx 行为不一致
|
||
|
||
必需的修复：
|
||
|
||
1. 为 Pydantic 字段添加长度和枚举约束
|
||
2. 明确验证 base64 格式
|
||
3. 更防御性地规范化文件名处理
|
||
4. 添加前端预检查大小/类型作为 UX
|
||
|
||
验收标准：
|
||
|
||
- 畸形请求尽早失败并返回确定性的 4xx 响应
|
||
|
||
### P1-03 前端自动化覆盖率基本缺失
|
||
|
||
当前状态：
|
||
|
||
- 后端有针对性的单元/集成风格测试
|
||
- 前端没有配置测试运行器
|
||
- 核心用户路径没有 E2E 覆盖率
|
||
|
||
重要说明：
|
||
|
||
- `backend/tests/test_main_cancel.py` 仍然发送过时的 `X-API-Key` 头；测试通过仅仅是因为后端忽略它们
|
||
|
||
风险：
|
||
|
||
- 编辑器、上传、OCR、转换和设置的回归将会遗漏
|
||
|
||
必需的修复：
|
||
|
||
1. 添加前端单元/组件测试
|
||
2. 为补全、取消、上传、OCR 和转换添加 E2E 覆盖率
|
||
3. 从后端测试中移除过时的认证假设
|
||
|
||
验收标准：
|
||
|
||
- 核心用户旅程在 CI 中自动覆盖
|
||
|
||
### P1-04 健康检查端点存在，但就绪性浅且缺少可观测性
|
||
|
||
当前状态：
|
||
|
||
- `/health/live` 存在
|
||
- `/health/ready` 存在
|
||
- 就绪性实际上不检查上游模型可用性
|
||
- 没有指标端点
|
||
- 没有追踪
|
||
- 没有告警定义
|
||
|
||
风险：
|
||
|
||
- 运行时故障检测太晚
|
||
- 平台探针可能报告健康而上游依赖不可用
|
||
|
||
必需的修复：
|
||
|
||
1. 使就绪性反映关键依赖状态
|
||
2. 添加请求/延迟/错误指标
|
||
3. 为上游故障和饱和添加告警阈值
|
||
4. 为关键路由定义仪表板
|
||
|
||
验收标准：
|
||
|
||
- 运营商可以快速检测模型依赖故障
|
||
- 请求成功率和延迟可观测
|
||
|
||
### P1-05 Service Worker 实现存在但被禁用
|
||
|
||
当前状态：
|
||
|
||
- `public/sw.js` 存在
|
||
- `src/main.js` 用 `&& false` 硬禁用注册
|
||
- Service Worker 策略是手写的并通过静态缓存名称版本化
|
||
|
||
风险：
|
||
|
||
- 当前仓库包含未被实际使用的休眠 PWA 逻辑
|
||
- 如果随意重新启用，更新和缓存行为可能很脆弱
|
||
|
||
必需的修复：
|
||
|
||
1. 确定 PWA 是否在生产范围内
|
||
2. 如果是，采用维护的策略如 Vite PWA/Workbox
|
||
3. 如果不是，移除无用的 Service Worker 代码以减少混淆
|
||
|
||
验收标准：
|
||
|
||
- PWA 行为要么被有意支持和测试，要么被完全移除
|
||
|
||
### P1-06 背景图像持久化可能导致本地存储和内存膨胀
|
||
|
||
当前状态：
|
||
|
||
- 设置面板将上传的背景图像读取为 data URL
|
||
- 背景图像数据存储在 localStorage 中
|
||
- 没有对背景资产强制执行明确的大小上限
|
||
|
||
风险：
|
||
|
||
- 存储配额耗尽
|
||
- 大图像导致 UI 缓慢
|
||
- 跨浏览器的持久化行为脆弱
|
||
|
||
必需的修复：
|
||
|
||
1. 读取前在客户端添加大小上限
|
||
2. 持久化前调整大小/压缩
|
||
3. 对于较大的资产，优先使用 blob/object URL 或 IndexedDB
|
||
4. 为存储溢出添加迁移/错误处理
|
||
|
||
验收标准：
|
||
|
||
- 大图像不能降低启动或破坏设置持久化
|
||
|
||
---
|
||
|
||
## P2 重要后续工作
|
||
|
||
### P2-01 构建成功，但 bundle/chunk 策略仍然粗糙
|
||
|
||
验证的构建输出显示：
|
||
|
||
- `manualChunks` 生成许多空 chunk
|
||
- 一个与 Mermaid 相关的大型 chunk 超过 1 MB 压缩后
|
||
|
||
风险：
|
||
|
||
- 不必要的 chunk 开销
|
||
- 较弱的设备上冷启动较慢
|
||
|
||
必需的修复：
|
||
|
||
1. 简化 `manualChunks`
|
||
2. 延迟加载重型可选功能
|
||
3. 清理 chunk 后重新测量首次加载成本
|
||
|
||
### P2-02 OCR 缓存和图像哈希缓存没有明确的驱逐策略
|
||
|
||
当前状态：
|
||
|
||
- OCR 数据存储在内存中的 `Map`
|
||
- 哈希缓存也在内存中
|
||
- 没有 TTL
|
||
- 没有最大条目数
|
||
|
||
风险：
|
||
|
||
- 长时间会话会累积内存
|
||
|
||
必需的修复：
|
||
|
||
1. 添加 TTL 和条目边界
|
||
2. 如需要，暴露缓存指标用于调试
|
||
|
||
### P2-03 仓库仍然包含过时和混淆的工件
|
||
|
||
示例：
|
||
|
||
- `backend/geoip.py` 和 GeoLite DB 仍然存在，尽管 IP 地理定位在请求流程中不再活跃
|
||
- `backend/.env.example` 记录的变量不是代码使用的
|
||
- 后端测试仍然包含过时的 `X-API-Key`
|
||
|
||
风险：
|
||
|
||
- 未来维护者可能无意中重新引入已移除的行为
|
||
|
||
必需的修复：
|
||
|
||
1. 移除死代码和过时配置
|
||
2. 使测试和文档与当前实现保持一致
|
||
|
||
---
|
||
|
||
## 上线前必需的缺失证据
|
||
|
||
仓库目前不提供以下生产能力的证据：
|
||
|
||
- staging 部署管道
|
||
- 回滚程序
|
||
- 流量/负载测试结果
|
||
- 故障注入或混沌测试
|
||
- 备份/恢复程序
|
||
- 事件响应运行手册
|
||
- SLO/SLA 定义
|
||
- 安全扫描基线
|
||
- 依赖更新策略
|
||
- 隐私/数据保留文档
|
||
|
||
目前应将证据缺失视为未就绪，而不是隐式完成。
|
||
|
||
## 推荐的修复顺序
|
||
|
||
### 第一阶段：解除生产上线阻碍
|
||
|
||
1. 实现真正的限流和并发强制执行
|
||
2. 定义官方部署拓扑和工件
|
||
3. 添加 CI/CD 质量门禁
|
||
4. 加固和隔离文件处理工作负载
|
||
5. 修复后端环境配置契约
|
||
|
||
### 第二阶段：稳定运维和隐私姿态
|
||
|
||
1. 移除承载内容的日志
|
||
2. 加强请求验证
|
||
3. 深化就绪检查和指标
|
||
4. 添加前端和 E2E 自动化测试
|
||
|
||
### 第三阶段：性能和可维护性清理
|
||
|
||
1. 清理 chunk 策略
|
||
2. 限制 OCR/图像缓存
|
||
3. 移除过时代码和配置
|
||
4. 决定 PWA 支持是保留还是移除
|
||
|
||
## 最低上线门槛
|
||
|
||
至少在以下所有条件都满足之前，不应称该项目为生产就绪：
|
||
|
||
- 所有 `P0` 项目都已完成
|
||
- 日志不再捕获用户内容
|
||
- 前端和端到端自动化测试存在并在 CI 中运行
|
||
- 就绪性反映真实的上游依赖状态
|
||
- 部署和回滚已记录且可重现
|
||
- staging 环境已通过集成验证
|
||
- 至少执行了一次受控负载测试并经过审查
|
||
|
||
## 最终评估
|
||
|
||
与之前的清单相比，该项目已有实质性改进。几个严重的早期发现不再成立，特别是：
|
||
|
||
- 硬编码的认证密钥暴露
|
||
- 通配符式 CORS 姿态
|
||
- 默认公网 IP 收集
|
||
- 原始异常泄漏
|
||
|
||
然而，这一进展并不意味着已准备好投入生产。
|
||
|
||
当前仓库展示了有用的加固工作，但仍然缺乏生产服务预期的运维、测试、节流、部署和可观测性基线。
|