From 0150927ed5eb31bdca389f576f88f9234942218c Mon Sep 17 00:00:00 2001 From: WangDL Date: Tue, 19 May 2026 22:51:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E8=BF=9B=E5=BA=A6=20+=205/19=20=E5=B7=A5=E4=BD=9C=E6=97=A5?= =?UTF-8?q?=E5=BF=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 工作日志/2026-05-19.md | 137 ++++++++++++++++++++++++++++++++ 执行计划与任务清单.MD | 174 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 311 insertions(+) create mode 100644 工作日志/2026-05-19.md create mode 100644 执行计划与任务清单.MD diff --git a/工作日志/2026-05-19.md b/工作日志/2026-05-19.md new file mode 100644 index 0000000..df18f96 --- /dev/null +++ b/工作日志/2026-05-19.md @@ -0,0 +1,137 @@ +# 工作日志 — 2026-05-19 + +--- + +## 今天完成的工作 + +### 🖥️ 服务器部署（8核32G 蜂驰云 120.53.227.155） + +**基础环境：** +- 数据盘挂载 /data，9 个子目录 +- Docker 29.1.3（镜像源：tencentyun + daocloud） +- Node.js 22.22.2 / pnpm 11.1.3 / Python 3.11.15 / Git +- deploy 用户创建 + +**核心服务（Docker 自启）：** +- MySQL 8.0.46 → 127.0.0.1:3306（innodb_buffer_pool_size=8G） +- Redis 7 → 127.0.0.1:6379（noeviction） +- Qdrant → 127.0.0.1:6333（zhixi_chunks, 1024d Cosine） + +**后端部署：** +- NestJS 部署到 /opt/zhixi/backend，systemd 自启 +- Nginx + Let's Encrypt → `https://api.longde.cloud` +- DNS 从 4核4G 切换到 8核32G +- Gitea Runner 安装注册（systemd 自启） + +### 🗄️ 数据库 + +- 33 张表全部就位（3 个 migration 执行完成） +- ID 类型已是 String(cuid)，无需迁移 +- 新增：KnowledgeSource / KnowledgeChunk / ImportCandidate / BackupJob / MembershipPlan + +### 🔧 后端开发 + +**新增 NestJS 模块：** +- `src/modules/knowledge-source/` — 资料来源 CRUD + 自动生成 DocumentImport +- `src/modules/import-candidate/` — 候选知识点管理 + 接受时自动生成 KnowledgeItem +- `src/modules/rag/` — 内部 RAG API（7 个端点，@Public 绕过 JWT） + +**增强模块：** +- DocumentImport — 支持 claim/heartbeat/stale recovery +- UploadedFile — sha256 去重 + +### 🐍 Python RAG Worker + +`rag-worker/` 目录（10 个文件）： +- `main.py` — 主循环（轮询→认领→执行→心跳） +- `parser.py` — 文档解析（PDF/DOCX/TXT/MD/CSV/XLSX + OCR） +- `chunker.py` — 512 token + 64 overlap + 中文分句保护 +- `embedder.py` — bge-m3 via 硅基流动（batch 50） +- `indexer.py` — Qdrant upsert + 检索 + 软删除 +- `candidate_generator.py` — DeepSeek 生成候选知识点 +- `pipelines/import_pipeline.py` — 完整导入流程编排 +- `api_client.py` — 与 NestJS 内部 API 通信 +- `config.py` / `requirements.txt` + +### 🔑 AI Provider + +- DeepSeek 官方 Key ✅ +- 硅基流动 Key ✅（bge-m3 / bge-reranker-v2-m3 / Qwen3-VL-32B-Instruct / Qwen3-VL-32B-Thinking） +- 百度 OCR ⏳ 待开通 + +### 📄 文档更新 + +- 知识库设计.MD — 完善版（25 节，32 项决策） +- 服务器与数据库部署方案.MD — 完整版（13 节） +- 执行计划与任务清单.MD — 更新进度标记 +- 凭据配置/蜂驰云服务器凭据.md — 填入实际密钥 +- 凭据配置/轻量云服务器凭据.md — 更新角色 + HTTPS 状态 + +--- + +## 服务器连接信息 + +| 服务器 | IP | SSH | +|--------|-----|-----| +| 4核4G 轻量云 | 81.70.187.179 | `ssh -i WangDL.pem ubuntu@81.70.187.179` | +| 8核32G 蜂驰云 | 120.53.227.155 | `ssh -i zhixi.pem ubuntu@120.53.227.155` | + +SSH 密钥位置：`startup-plan/凭据配置/WangDL.pem` 和 `zhixi.pem` + +--- + +## 8核32G 上运行的服务 + +| 服务 | 管理方式 | 命令 | +|------|---------|------| +| NestJS API | systemd | `sudo systemctl restart zhixi-api` | +| Gitea Runner | systemd | `sudo systemctl restart gitea-runner` | +| MySQL | Docker | `docker restart mysql` | +| Redis | Docker | `docker restart redis` | +| Qdrant | Docker | `docker restart qdrant` | +| Nginx | systemd | `sudo systemctl restart nginx` | + +**日志位置：** +- NestJS: `/data/logs/nestjs.log` / `nestjs-error.log` +- Nginx: `/var/log/nginx/` +- Docker: `docker logs ` + +**代码位置：** +- `/opt/zhixi/backend/` — NestJS（git 仓库） +- `/opt/zhixi/rag-worker/` — Python Worker（待部署） +- `/opt/zhixi/env/.env.production` — 环境变量 +- `/opt/zhixi/runner/` — Gitea Runner + +--- + +## 明天继续 + +1. **Python Worker 部署到 8核32G**（最高优先） + ```bash + ssh -i zhixi.pem ubuntu@120.53.227.155 + cd /opt/zhixi/backend + git pull + cd rag-worker + pip3.11 install -r requirements.txt + # 创建 systemd service 启动 main.py + ``` + +2. **COS Bucket 创建**（腾讯云控制台） +3. **百度 OCR 开通** +4. **4核4G 安装 gitea-runner-web** +5. **编写 CI/CD workflow 文件** + +--- + +## 5月20日继续工作的准备 + +**换电脑后需要：** +1. 将 `startup-plan/凭据配置/` 目录下的 `zhixi.pem` 和 `WangDL.pem` 复制到新电脑 +2. 将 `api-server/` 仓库 clone 到新电脑（或直接通过 VS Code Remote SSH 在服务器上开发） +3. 所有设计文档在 `startup-plan/技术设计/` 下，已推送到 Gitea +4. Gitea 地址：`https://git.longde.cloud`，账号 wangdl + +**关键凭据文件（已在 .gitignore，不会推送）：** +- `凭据配置/蜂驰云服务器凭据.md` — 所有 8核32G 密码/密钥 +- `凭据配置/轻量云服务器凭据.md` — 4核4G + Gitea 账号 +- `凭据配置/zhixi.pem` / `WangDL.pem` — SSH 密钥 diff --git a/执行计划与任务清单.MD b/执行计划与任务清单.MD new file mode 100644 index 0000000..2b146fd --- /dev/null +++ b/执行计划与任务清单.MD @@ -0,0 +1,174 @@ +# 知习执行计划与任务清单 + +> 最后更新：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** | ✅ 代码完成，待部署到服务器 | +| **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 自启 | +| 4.2 | 4核4G 安装 gitea-runner-web | ⏳ 待安装 | +| 4.3 | deploy-backend.yml | ⏳ 待编写 | +| 4.4 | deploy-web.yml | ⏳ 待编写 | +| 4.5 | Gitea Secrets 配置 | ⏳ 待配置 | + +--- + +## 阶段五：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-D：AI Provider（✅ 已配置） + +| # | 任务 | 状态 | +|---|------|------| +| 6.16 | DeepSeek 官方 API Key | ✅ | +| 6.17 | 硅基流动 API Key（embedding/rerank/vision）| ✅ | +| 6.18 | 百度 OCR | ⏳ 待开通 | + +--- + +## 阶段七：学习引擎（⚪ 待开始） + +| # | 任务 | 状态 | +|---|------|------| +| 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 成本日志 | ⏳ | + +--- + +## 待办速查（明天优先） + +1. 🔴 **Python Worker 部署** — 在 8核32G 安装依赖 `pip3.11 install -r requirements.txt`，配置 .env，编写 systemd service +2. 🔴 **COS Bucket 创建** — 腾讯云控制台创建 `zhixi-prod` bucket，配置 SecretId/SecretKey +3. 🟡 **百度 OCR 开通** +4. 🟡 **4核4G 安装 gitea-runner-web** +5. 🟡 **deploy-backend.yml / deploy-web.yml 编写**