startup-plan/执行计划与任务清单.MD

知习执行计划与任务清单

最后更新：2026-05-19 | 依据：知识库设计 + 服务器部署方案 + 凭据信息

---

当前状态速览

资产	状态
4核4G 轻量云 (81.70.187.179)	✅ 工具服务器 — Web + Gitea + Nginx，旧 MySQL/Redis 退役
8核32G 蜂驰云 (120.53.227.155)	✅ 生产主服务器 — NestJS + MySQL + Redis + Qdrant + Gitea Runner
域名 longde.cloud	✅ api.longde.cloud DNS 已切到 8核32G，HTTPS 已生效
数据库	✅ MySQL 8.0.46，zhixi_prod 已迁移，33 张表
后端代码	✅ NestJS 生产运行，build 通过，systemd 自启
Python RAG Worker	🔶 代码已部署到 /opt/zhixi/backend/rag-worker/，依赖 + systemd 待补
iOS 客户端	✅ 已基本完成 UI，待对接知识库 API
Web 产品页	✅ 已上线，Web 仓库 CI/CD

---

阶段一：8核32G 基础环境（✅ 已完成）

#	任务	状态
1.1	数据盘挂载到 /data + 子目录	✅
1.2	安装 Docker 29.1.3 + Docker Compose 2.40.3	✅
1.3	安装 Git + Node.js 22.22.2 + pnpm 11.1.3 + Python 3.11.15	✅
1.4	安全组配置（22/80/443 开，其余仅 127.0.0.1）	✅
1.5	创建 deploy 用户	✅
1.6	安装 logrotate	✅

---

阶段二：核心服务部署（✅ 已完成）

#	任务	状态
2.1	Docker 部署 MySQL 8.0.46（innodb_buffer_pool_size=8G, max_connections=100）	✅
2.2	创建 zhixi_prod 数据库 + zhixi_user 账号	✅
2.3	Docker 部署 Redis 7（512MB, noeviction, AOF+RDB）	✅
2.4	Docker 部署 Qdrant（collection: zhixi_chunks, 1024d, Cosine, 1 shard）	✅
2.5	三服务联通验证	✅

---

阶段三：数据库迁移与 ID 改造（✅ 已完成）

#	任务	状态
3.1	ID 类型检查	✅ 已是 String(cuid)，无需改造
3.2	Prisma migration 初始化	✅ 3 个 migration 已执行
3.3	数据迁移（4核→8核）	✅ 无实际数据，结构重建即完成

---

阶段四：CI/CD 搭建（✅ 已完成）

#	任务	状态
4.1	8核32G 安装 gitea-runner-prod	✅ systemd 自启，labels: prod/backend/rag/docker
4.2	4核4G 安装 gitea-runner-web	✅ systemd 自启，labels: ubuntu-latest
4.3	deploy-backend.yml	✅ 4 步骤：checkout → infrastructure → rsync worker → health
4.4	deploy-web.yml	✅ /tmp/web-projects/.gitea/workflows/deploy.yml 已验证
4.5	Gitea Secrets 配置	✅ 密钥放在服务器本地 .env
4.6	Gitea 1.22.6 → 1.23.8 升级	✅ 修复 Actions 模板渲染 bug + UpdateTask 状态更新问题

---

阶段五：NestJS 后端迁移（✅ 已完成）

#	任务	状态
5.1	clone api-server 到 /opt/zhixi/backend	✅
5.2	pnpm install + pnpm build	✅
5.3	systemd zhixi-api.service	✅ 开机自启
5.4	Nginx + Let's Encrypt HTTPS	✅ api.longde.cloud SSL 已生效
5.5	DNS api.longde.cloud → 8核32G	✅
5.6	iOS 可通过 HTTPS 访问	✅ API 正常返回

---

阶段六：知识库核心开发（🟡 进行中）

6-A：Prisma 数据模型（✅ 已完成）

#	任务	状态
6.1	新增 KnowledgeSource / KnowledgeChunk / ImportCandidate / BackupJob / MembershipPlan	✅
6.2	增强 DocumentImport（sourceId/workerId/heartbeatAt/retryCount/step）	✅
6.3	增强 UploadedFile（sha256/purpose）	✅
6.4	增强 KnowledgeItem（sourceDeleted/snapshot 字段）	✅
6.5	migration 生成 + 生产部署	✅ 33 张表

6-B：后端模块（✅ 已完成）

#	任务	状态
6.6	KnowledgeSource 模块（CRUD + 创建时自动生成 DocumentImport）	✅
6.7	ImportCandidate 模块（查询/接受/拒绝/批量接受，接受时自动生成 KnowledgeItem）	✅
6.8	内部 RAG API（任务轮询/认领/心跳/状态/chunks/candidates）	✅ @Public 绕过 JWT

6-C：Python RAG Worker（✅ 已完成部署）

#	任务	状态
6.9	main.py 主循环（轮询→认领→执行）	✅
6.10	parser.py（PDF/DOCX/TXT/MD/CSV/XLSX + OCR）	✅
6.11	chunker.py（512 tokens + 64 overlap + 中文分句保护）	✅
6.12	embedder.py（bge-m3 via 硅基流动）	✅
6.13	indexer.py（Qdrant upsert + 检索 + 软删除）	✅
6.14	candidate_generator.py（DeepSeek 生成候选知识点）	✅
6.15	import_pipeline.py（完整导入流程编排）	✅
6.15a	代码推送到 8核32G /opt/zhixi/backend/rag-worker/	✅
6.15b	.env 配置（API 密钥 / endpoint）	✅
6.15c	pip install -r requirements.txt	✅ 28+ packages via tencentyun mirror
6.15d	创建 systemd zhixi-worker.service	✅ enabled active，轮询正常

6-D：AI Provider（✅ 已完成）

#	任务	状态
6.16	DeepSeek 官方 API Key	✅
6.17	硅基流动 API Key（embedding/rerank/vision）	✅
6.18	百度 OCR	✅ AppID 7767914，密钥已存入凭据

---

阶段七：学习引擎（⚪ 待开始）

#	任务	状态
7.1	主动回忆接口	⏳
7.2	AI 诊断（DeepSeek thinking → FocusItem）	⏳
7.3	复习卡生成	⏳
7.4	学习记录	⏳

---

阶段八：知识库对话（⚪ 待开始）

#	任务	状态
8.1	RAG 检索 pipeline（Top-50 → rerank Top-5~8）	⏳
8.2	知识库对话接口（answer + citations + suggestedActions）	⏳
8.3	Chat session + messages	⏳

---

阶段九：运维配套（⚠️ 部分完成）

#	任务	状态
9.1	MySQL 每日备份 + 同步 COS	⏳
9.2	Qdrant 每日快照 + 同步 COS	⏳
9.3	Stale job recovery（定时任务）	⏳
9.4	定时物理清理	⏳
9.5	/health 端点	✅ GET /api 返回 {"status":"ok"}

---

阶段十：额度与后台（⚪ 待开始）

#	任务	状态
10.1	membership_plans 表	✅ 表已建，待填充数据
10.2	额度检查中间件	⏳
10.3	后台管理 API	⏳
10.4	AI 成本日志	⏳

---

待办速查（5/20 更新）

1. 🔴 Python Worker 补全部署 ✅ 已完成 — systemd zhixi-worker.service 运行中
2. 🔴 4核4G 安装 gitea-runner-web ✅ 已完成 — 单一 runner 覆盖两端
3. 🟡 百度 OCR 开通 ✅ 已完成 — AppID 7767914，密钥已存
4. 🟡 COS Bucket 验证 ✅ Bucket zhixi-1259685406 存在，SecretId/Key 已验证可访问
5. 🟡 Rerank 模块代码 ✅ reranker.py 已推送，bge-reranker-v2-m3 验证通过
6. 🔴 CI/CD 流水线修复 ✅ 精简为 4 步，Runner 正确匹配，Gitea 升级到 1.23.8
7. 🟡 知识库对话接口（RAG 检索→rerank→DeepSeek 回答+citations）
8. 🟡 知识库级联删除
9. 🟢 MySQL/Qdrant 备份脚本 + cron
10. 🟢 物理清理定时任务
11. ⬜ 阶段七：学习引擎（ActiveRecall→AIAnalysis→FocusItem→ReviewCard）
12. ⬜ 阶段八：知识库对话（Chat session + 多轮对话）
13. ⬜ 阶段十：后台管理 + 额度检查