QuestionProject/ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md

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. 确认已经执行数据库备份。

本地开发启动

cd ai_knowledge_base_v2
docker compose -f docker-compose.dev.yml up --build

如果用户端问答需要直读飞书知识库，需要在启动前配置后端运行环境变量：

export FEISHU_APP_ID=你的飞书应用AppID
export FEISHU_APP_SECRET=你的飞书应用AppSecret
docker compose -f docker-compose.dev.yml up -d --build backend user-client admin-web

也可以在 ai_knowledge_base_v2/.env 中配置 FEISHU_APP_ID、FEISHU_APP_SECRET 和 FEISHU_SEARCH_URL。后台“知识库管理”只维护 SpaceID、NodeID 和启用状态；飞书应用凭证不存放在知识库记录中。若使用独立飞书检索适配服务，则在后台“系统配置”填写飞书检索服务地址，后端会优先调用该地址。

默认地址：

• 用户端 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

开发阶段默认账号

用户端：

手机号：任意 11 位手机号
验证码：123456

管理后台：

账号：admin
密码：admin123456

生产环境必须修改默认管理员密码。

数据库迁移

后端容器启动时会执行：

alembic upgrade head

如果需要手工执行：

cd apps/backend
alembic upgrade head

备份

可使用脚本：

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、域名、访问日志和基础监控。