feat: 凭证生成、成本分析、AI问答、前端页面、集成测试与E2E测试
- 后端: 凭证生成引擎、金蝶导出器、凭证模板服务 - 后端: 成本分析服务、AI问答服务 - 后端: 科目映射CRUD API、分析API、QA API - 后端: 集成测试(认证/任务/凭证) 49个测试全部通过 - 前端: 凭证管理、成本分析、导出中心、知识库、系统设置页面 - 前端: AuthGuard认证守卫、Dashboard AI聊天功能 - 前端: Playwright E2E测试 16 passed, 1 skipped - 基础设施: Docker Compose、Nginx反向代理、.env.example - 文档: 用户手册、管理员手册、发布检查清单
This commit is contained in:
@@ -0,0 +1,160 @@
|
||||
# S2F 管理员手册
|
||||
|
||||
## 1. 系统部署
|
||||
|
||||
### 1.1 Docker 部署(推荐)
|
||||
|
||||
```bash
|
||||
# 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 本地开发部署
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
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 初始化
|
||||
```bash
|
||||
docker-compose exec backend python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
|
||||
```
|
||||
|
||||
### 3.2 备份
|
||||
```bash
|
||||
# 手动备份
|
||||
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 恢复
|
||||
```bash
|
||||
docker-compose exec -T postgres psql -U s2f_user s2f_db < backup_20240101.sql
|
||||
```
|
||||
|
||||
## 4. 监控与日志
|
||||
|
||||
### 4.1 查看日志
|
||||
```bash
|
||||
# 后端日志
|
||||
docker-compose logs -f backend
|
||||
|
||||
# 前端日志
|
||||
docker-compose logs -f frontend
|
||||
|
||||
# Nginx 日志
|
||||
docker-compose logs -f nginx
|
||||
|
||||
# 数据库日志
|
||||
docker-compose logs -f postgres
|
||||
```
|
||||
|
||||
### 4.2 健康检查
|
||||
```bash
|
||||
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 服务无法启动
|
||||
```bash
|
||||
# 检查容器状态
|
||||
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 更新代码
|
||||
```bash
|
||||
git pull
|
||||
docker-compose build
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 7.2 数据库迁移
|
||||
```bash
|
||||
docker-compose exec backend alembic upgrade head
|
||||
```
|
||||
Reference in New Issue
Block a user