selfrelease
5278190750
- 后端: 凭证生成引擎、金蝶导出器、凭证模板服务 - 后端: 成本分析服务、AI问答服务 - 后端: 科目映射CRUD API、分析API、QA API - 后端: 集成测试(认证/任务/凭证) 49个测试全部通过 - 前端: 凭证管理、成本分析、导出中心、知识库、系统设置页面 - 前端: AuthGuard认证守卫、Dashboard AI聊天功能 - 前端: Playwright E2E测试 16 passed, 1 skipped - 基础设施: Docker Compose、Nginx反向代理、.env.example - 文档: 用户手册、管理员手册、发布检查清单
3.5 KiB
3.5 KiB
S2F 管理员手册
1. 系统部署
1.1 Docker 部署（推荐）
# 1. 复制环境变量
cp .env.example .env
# 2. 编辑 .env，配置关键参数
# - DB_PASSWORD: 数据库密码（生产环境务必修改）
# - SECRET_KEY: JWT 签名密钥
# - JWT_SECRET_KEY: JWT 加密密钥
# - ZHIPU_API_KEY: 智谱 AI API Key
# - ALLOWED_ORIGINS: 前端访问地址
# 3. 启动所有服务
docker-compose up -d
# 4. 初始化数据库
docker-compose exec backend python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
# 5. 验证服务
curl http://localhost:8000/api/health
1.2 本地开发部署
# 后端
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# 前端
cd frontend
npm install
npm run dev
2. 环境变量说明
| 变量 | 说明 | 默认值 |
|---|---|---|
| DB_NAME | 数据库名 | s2f_db |
| DB_USER | 数据库用户 | s2f_user |
| DB_PASSWORD | 数据库密码 | s2f_password |
| SECRET_KEY | 应用密钥 | change-me-in-production |
| JWT_SECRET_KEY | JWT 密钥 | change-me-in-production |
| AI_PROVIDER | AI 服务商 | zhipu |
| ZHIPU_API_KEY | 智谱 API Key | - |
| OPENAI_API_KEY | OpenAI API Key | - |
| ALLOWED_ORIGINS | CORS 允许来源 | http://localhost:3000 |
| DEBUG | 调试模式 | false |
| LOG_LEVEL | 日志级别 | INFO |
3. 数据库管理
3.1 初始化
docker-compose exec backend python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
3.2 备份
# 手动备份
docker-compose exec postgres pg_dump -U s2f_user s2f_db > backup_$(date +%Y%m%d).sql
# 定时备份（crontab）
0 2 * * * docker-compose exec -T postgres pg_dump -U s2f_user s2f_db > /backups/s2f_$(date +\%Y\%m\%d).sql
3.3 恢复
docker-compose exec -T postgres psql -U s2f_user s2f_db < backup_20240101.sql
4. 监控与日志
4.1 查看日志
# 后端日志
docker-compose logs -f backend
# 前端日志
docker-compose logs -f frontend
# Nginx 日志
docker-compose logs -f nginx
# 数据库日志
docker-compose logs -f postgres
4.2 健康检查
curl http://localhost:8000/api/health
4.3 性能监控
- 后端 API 文档：http://localhost:8000/docs
- 监控指标：API 响应时间、数据库连接数、Redis 内存
5. 安全配置
5.1 生产环境检查清单
- 修改 DB_PASSWORD
- 修改 SECRET_KEY 和 JWT_SECRET_KEY
- 配置正确的 ALLOWED_ORIGINS
- 设置 DEBUG=false
- 配置 HTTPS（通过 Nginx）
- 设置防火墙规则
5.2 AI API Key 管理
- API Key 存储在 .env 文件中，不进入 Git
- 定期轮换 API Key
- 监控 API 调用量和成本
6. 故障排除
6.1 服务无法启动
# 检查容器状态
docker-compose ps
# 查看错误日志
docker-compose logs backend
docker-compose logs postgres
6.2 数据库连接失败
- 检查 PostgreSQL 容器是否运行
- 检查 DATABASE_URL 配置
- 检查网络连通性
6.3 AI 功能不可用
- 检查 ZHIPU_API_KEY 或 OPENAI_API_KEY 是否配置
- 检查网络是否能访问 AI API
- 查看后端日志中的 AI 调用错误
6.4 前端无法访问后端
- 检查 CORS 配置（ALLOWED_ORIGINS）
- 检查 Nginx 反向代理配置
- 检查后端服务是否正常运行
7. 更新与升级
7.1 更新代码
git pull
docker-compose build
docker-compose up -d
7.2 数据库迁移
docker-compose exec backend alembic upgrade head