From 08dd371480db7de080804f5a1d04be8f1dc240c5 Mon Sep 17 00:00:00 2001
From: Nelson <1475262689@qq.com>
Date: Mon, 6 Jul 2026 18:14:36 +0800
Subject: [PATCH] Add V2 phase six verification assets

---
 .../deployment/DEPLOYMENT_GUIDE.md            | 97 +++++++++++++++++++
 .../deployment/RELEASE_CHECKLIST.md           | 42 ++++++++
 .../development_records/README.md             |  1 +
 ai_knowledge_base_v2/scripts/mysql_backup.sh  | 24 +++++
 ai_knowledge_base_v2/scripts/phase6_verify.sh | 34 +++++++
 .../2026-07-06-phase6-verification.md         | 47 +++++++++
 6 files changed, 245 insertions(+)
 create mode 100644 ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md
 create mode 100644 ai_knowledge_base_v2/deployment/RELEASE_CHECKLIST.md
 create mode 100755 ai_knowledge_base_v2/scripts/mysql_backup.sh
 create mode 100755 ai_knowledge_base_v2/scripts/phase6_verify.sh
 create mode 100644 ai_knowledge_base_v2/test_records/2026-07-06-phase6-verification.md

diff --git a/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md
new file mode 100644
index 0000000..6776c38
--- /dev/null
+++ b/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md
@@ -0,0 +1,97 @@
+# AI 知识库系统 V2 部署手册
+
+## 适用范围
+
+本文档用于 V2 当前版本的部署交接。当前版本包含：
+
+- 后端：FastAPI
+- 用户端 H5：Vue 3
+- 管理后台：Vue 3 + Element Plus
+- 数据库：MySQL 8.x
+
+## 部署前检查
+
+1. 确认服务器已经安装 Docker 和 Docker Compose。
+2. 确认 MySQL 数据目录有持久化卷或外部数据库。
+3. 确认以下密钥不再使用开发默认值：
+   - `JWT_SECRET_KEY`
+   - `BOOTSTRAP_ADMIN_PASSWORD`
+   - 模型 API Key
+   - 飞书检索服务凭证或适配服务密钥
+4. 确认防火墙只开放必要端口。
+5. 确认已经执行数据库备份。
+
+## 本地开发启动
+
+```bash
+cd ai_knowledge_base_v2
+docker compose -f docker-compose.dev.yml up --build
+```
+
+默认地址：
+
+- 用户端 H5：`http://127.0.0.1:5173/`
+- 管理后台：`http://127.0.0.1:5174/`
+- 后端健康检查：`http://127.0.0.1:8100/api/health`
+- MySQL：`127.0.0.1:3307`
+
+## 开发阶段默认账号
+
+用户端：
+
+```text
+手机号：任意 11 位手机号
+验证码：123456
+```
+
+管理后台：
+
+```text
+账号：admin
+密码：admin123456
+```
+
+生产环境必须修改默认管理员密码。
+
+## 数据库迁移
+
+后端容器启动时会执行：
+
+```bash
+alembic upgrade head
+```
+
+如果需要手工执行：
+
+```bash
+cd apps/backend
+alembic upgrade head
+```
+
+## 备份
+
+可使用脚本：
+
+```bash
+cd ai_knowledge_base_v2
+BACKUP_DIR=./backups ./scripts/mysql_backup.sh
+```
+
+## 回滚原则
+
+1. 先停止新版本服务。
+2. 切回上一版镜像或上一版 Git commit。
+3. 如果数据库迁移不可逆，先从备份恢复。
+4. 恢复后检查：
+   - `/api/health`
+   - 用户端登录
+   - 用户端提问
+   - 管理后台登录
+   - 管理后台数据列表
+
+## 生产待补事项
+
+- 前端生产镜像建议改为 Nginx 静态服务，不使用 Vite dev server。
+- 模型 API Key 建议加密保存或使用密钥管理服务。
+- 后端需要接入结构化日志采集。
+- 需要配置 HTTPS、域名、访问日志和基础监控。
diff --git a/ai_knowledge_base_v2/deployment/RELEASE_CHECKLIST.md b/ai_knowledge_base_v2/deployment/RELEASE_CHECKLIST.md
new file mode 100644
index 0000000..a29f232
--- /dev/null
+++ b/ai_knowledge_base_v2/deployment/RELEASE_CHECKLIST.md
@@ -0,0 +1,42 @@
+# V2 发布检查清单
+
+## 发布前
+
+- [ ] 已确认当前 Git commit。
+- [ ] 已执行 `./scripts/phase6_verify.sh`。
+- [ ] 已备份 MySQL 数据库。
+- [ ] 已替换开发默认管理员密码。
+- [ ] 已替换 `JWT_SECRET_KEY`。
+- [ ] 已确认飞书检索配置。
+- [ ] 已确认模型配置和额度策略。
+- [ ] 已确认前端 API 地址。
+
+## 发布中
+
+- [ ] 拉取最新代码或镜像。
+- [ ] 执行数据库迁移。
+- [ ] 启动后端服务。
+- [ ] 启动用户端 H5。
+- [ ] 启动管理后台。
+- [ ] 检查后端健康接口。
+
+## 发布后
+
+- [ ] 用户端可以登录。
+- [ ] 用户端可以创建会话。
+- [ ] 用户端可以提问并收到回答。
+- [ ] 无命中问题返回固定兜底。
+- [ ] 管理后台可以登录。
+- [ ] 管理后台可以查看 Dashboard。
+- [ ] 管理后台可以保存 Prompt。
+- [ ] 管理后台可以新增知识库。
+- [ ] AI 请求日志有记录。
+- [ ] 操作日志有记录。
+
+## 回滚触发条件
+
+- 用户端无法登录。
+- 用户端无法完成提问主链路。
+- 后台无法登录。
+- 数据库迁移失败且无法快速修复。
+- 外部服务异常导致核心链路不可用。
diff --git a/ai_knowledge_base_v2/development_records/README.md b/ai_knowledge_base_v2/development_records/README.md
index c64f027..6566ba0 100644
--- a/ai_knowledge_base_v2/development_records/README.md
+++ b/ai_knowledge_base_v2/development_records/README.md
@@ -32,3 +32,4 @@
 | `2026-07-06-phase3-user-client-completion.md` | 阶段三用户端 H5 主链路补齐记录。 |
 | `2026-07-06-phase4-rag-external-services.md` | 阶段四 RAG 和外部服务接入骨架记录。 |
 | `2026-07-06-phase5-admin-console.md` | 阶段五管理后台记录。 |
+| `../test_records/2026-07-06-phase6-verification.md` | 阶段六验证记录。 |
diff --git a/ai_knowledge_base_v2/scripts/mysql_backup.sh b/ai_knowledge_base_v2/scripts/mysql_backup.sh
new file mode 100755
index 0000000..37c546f
--- /dev/null
+++ b/ai_knowledge_base_v2/scripts/mysql_backup.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BACKUP_DIR="${BACKUP_DIR:-./backups}"
+MYSQL_HOST="${MYSQL_HOST:-127.0.0.1}"
+MYSQL_PORT="${MYSQL_PORT:-3307}"
+MYSQL_USER="${MYSQL_USER:-ai_kb}"
+MYSQL_PASSWORD="${MYSQL_PASSWORD:-ai_kb}"
+MYSQL_DATABASE="${MYSQL_DATABASE:-ai_knowledge_base_v2}"
+
+mkdir -p "$BACKUP_DIR"
+OUTPUT_FILE="$BACKUP_DIR/${MYSQL_DATABASE}_$(date +%Y%m%d_%H%M%S).sql"
+
+mysqldump \
+  -h "$MYSQL_HOST" \
+  -P "$MYSQL_PORT" \
+  -u "$MYSQL_USER" \
+  -p"$MYSQL_PASSWORD" \
+  --single-transaction \
+  --routines \
+  --triggers \
+  "$MYSQL_DATABASE" > "$OUTPUT_FILE"
+
+echo "备份完成：$OUTPUT_FILE"
diff --git a/ai_knowledge_base_v2/scripts/phase6_verify.sh b/ai_knowledge_base_v2/scripts/phase6_verify.sh
new file mode 100755
index 0000000..1ea10b8
--- /dev/null
+++ b/ai_knowledge_base_v2/scripts/phase6_verify.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+echo "== 后端编译检查 =="
+cd "$ROOT_DIR/apps/backend"
+./.venv/bin/python -m compileall app
+
+echo "== 后端 OpenAPI 检查 =="
+DATABASE_URL=sqlite:///:memory: ./.venv/bin/python - <<'PY'
+from app.main import app
+paths = app.openapi().get("paths", {})
+print(f"OpenAPI paths: {len(paths)}")
+assert len(paths) >= 32
+PY
+
+echo "== Alembic MySQL 静态 SQL 检查 =="
+./.venv/bin/alembic upgrade head --sql >/tmp/ai_kb_v2_migration.sql
+wc -l /tmp/ai_kb_v2_migration.sql
+
+echo "== 用户端 H5 构建 =="
+cd "$ROOT_DIR/apps/user-client"
+npm run build
+
+echo "== 管理后台构建 =="
+cd "$ROOT_DIR/apps/admin-web"
+npm run build
+
+echo "== Docker Compose 配置检查 =="
+cd "$ROOT_DIR"
+docker compose -f docker-compose.dev.yml config --quiet
+
+echo "阶段六自动验证完成"
diff --git a/ai_knowledge_base_v2/test_records/2026-07-06-phase6-verification.md b/ai_knowledge_base_v2/test_records/2026-07-06-phase6-verification.md
new file mode 100644
index 0000000..a99fd8f
--- /dev/null
+++ b/ai_knowledge_base_v2/test_records/2026-07-06-phase6-verification.md
@@ -0,0 +1,47 @@
+# 阶段六验证记录
+
+日期：2026-07-06
+
+## 验证范围
+
+本次验证覆盖当前 V2 代码状态：
+
+- 后端基础接口
+- 用户端 H5 构建
+- 管理后台构建
+- Alembic 迁移 SQL 生成
+- Docker Compose 配置
+- RAG/模型 mock 服务级逻辑
+
+## 已执行验证
+
+| 验证项 | 结果 | 说明 |
+| --- | --- | --- |
+| 后端 `python -m compileall app` | 通过 | 后端 Python 文件可编译。 |
+| FastAPI OpenAPI 导入 | 通过 | 当前接口路径数为 32。 |
+| Alembic MySQL 静态 SQL 生成 | 通过 | 可生成初始迁移 SQL。 |
+| 用户端 H5 `npm run build` | 通过 | Vue H5 构建成功。 |
+| 管理后台 `npm run build` | 通过 | Element Plus 有体积提示，但构建成功。 |
+| Docker Compose 配置检查 | 通过 | `docker compose config --quiet` 无报错。 |
+| RAG 命中服务级验证 | 通过 | 命中问题返回带来源的 mock 回答。 |
+| RAG 无命中服务级验证 | 通过 | 返回固定兜底文案。 |
+
+## 未完整执行的验证
+
+- 未执行真实飞书知识库检索，因为缺少飞书账号、权限和真实 API 返回结构确认。
+- 未执行真实大模型调用，因为缺少生产模型配置和 API Key。
+- 未执行完整 Docker 容器启动验收，因为此前 Docker Hub 基础镜像下载速度过慢，容易拖慢开发节奏。
+- 未执行浏览器人工全流程点测截图，后续进入测试阶段需要补充。
+
+## 当前验收结论
+
+当前版本已经完成阶段一到阶段六的工程闭环：
+
+1. 有需求、架构和开发决策记录。
+2. 有后端基础工程、数据模型和核心接口。
+3. 有用户端 H5 主链路。
+4. 有 RAG/外部服务 provider 骨架。
+5. 有管理后台第一版。
+6. 有验证脚本、部署手册、发布检查清单和备份脚本。
+
+当前版本适合进入“真实外部服务接入前的联调测试”。