# 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
```