selfrelease
5278190750
- 后端: 凭证生成引擎、金蝶导出器、凭证模板服务 - 后端: 成本分析服务、AI问答服务 - 后端: 科目映射CRUD API、分析API、QA API - 后端: 集成测试(认证/任务/凭证) 49个测试全部通过 - 前端: 凭证管理、成本分析、导出中心、知识库、系统设置页面 - 前端: AuthGuard认证守卫、Dashboard AI聊天功能 - 前端: Playwright E2E测试 16 passed, 1 skipped - 基础设施: Docker Compose、Nginx反向代理、.env.example - 文档: 用户手册、管理员手册、发布检查清单
161 lines
3.5 KiB
Markdown
161 lines
3.5 KiB
Markdown
# 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
|
||
```
|