smart-project-pricing/docs/系统管理手册.md

# 智能项目定价模型 - 系统管理手册

> **版本**：v1.0  
> **更新日期**：2026-01-20  
> **适用对象**：系统管理员、运维人员

---

## 目录

1. [系统架构](#1-系统架构)
2. [部署指南](#2-部署指南)
3. [配置管理](#3-配置管理)
4. [日常运维](#4-日常运维)
5. [备份与恢复](#5-备份与恢复)
6. [监控与告警](#6-监控与告警)
7. [故障排查](#7-故障排查)
8. [安全规范](#8-安全规范)
9. [附录](#9-附录)

---

## 1. 系统架构

### 1.1 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| 后端 | Python + FastAPI | 3.11 |
| 前端 | Vue 3 + TypeScript | 3.x |
| 数据库 | MySQL | 8.0 |
| 容器 | Docker + Docker Compose | 24.x |
| 反向代理 | Nginx | 1.25 |

### 1.2 服务架构

```
                    用户浏览器
                         │
                         │ HTTPS (443)
                         ▼
                 ┌───────────────┐
                 │    Nginx      │  (nginx_proxy)
                 │  反向代理      │  端口: 80, 443
                 └───────┬───────┘
                         │
         ┌───────────────┴───────────────┐
         │                               │
         ▼                               ▼
┌─────────────────┐            ┌─────────────────┐
│ pricing-frontend│            │ pricing-backend │
│   Vue 3 SPA     │            │    FastAPI      │
│   端口: 80      │            │   端口: 8000    │
└─────────────────┘            └────────┬────────┘
                                        │
                               ┌────────┴────────┐
                               │                 │
                               ▼                 ▼
                      ┌─────────────┐   ┌─────────────┐
                      │pricing-mysql│   │  门户系统    │
                      │  MySQL 8.0  │   │  AI 配置    │
                      └─────────────┘   └─────────────┘
```

### 1.3 网络配置

| 网络 | 用途 |
|------|------|
| `pricing_network` | 定价系统内部通信 |
| `scrm_network` | 与门户系统通信（获取 AI 配置） |

### 1.4 数据卷

| 卷名 | 用途 |
|------|------|
| `pricing_mysql_data` | MySQL 数据持久化 |

---

## 2. 部署指南

### 2.1 环境要求

**硬件要求**：

| 资源 | 最低配置 | 推荐配置 |
|------|----------|----------|
| CPU | 2 核 | 4 核 |
| 内存 | 4 GB | 8 GB |
| 磁盘 | 40 GB | 100 GB |

**软件要求**：

- Docker 24.0+
- Docker Compose 2.20+
- Linux (推荐 Ubuntu 22.04 / Debian 12)

### 2.2 首次部署

#### 步骤 1：获取代码

```bash
git clone <repository_url> /opt/pricing-model
cd /opt/pricing-model
```

#### 步骤 2：配置环境变量

```bash
# 复制配置模板
cp env.example .env

# 编辑配置（修改数据库密码、密钥等）
vim .env

# 设置文件权限（重要！）
chmod 600 .env
```

**必须修改的配置项**：

```bash
# 数据库密码（请使用强密码）
MYSQL_ROOT_PASSWORD=your_strong_root_password
MYSQL_PASSWORD=your_strong_password

# 应用密钥（32位以上随机字符串）
SECRET_KEY=your_random_secret_key_at_least_32_chars

# 门户系统 API（确保网络可达）
PORTAL_CONFIG_API=http://portal-backend:8000/api/ai/internal/config
```

#### 步骤 3：创建外部网络

```bash
# 如果 scrm_network 不存在
docker network create scrm_network
```

#### 步骤 4：执行部署

```bash
./scripts/deploy.sh deploy
```

#### 步骤 5：配置 Nginx 反向代理

将 `nginx.conf` 添加到主机 Nginx 配置：

```bash
# 复制配置到 Nginx
cp nginx.conf /etc/nginx/sites-available/pricing.conf

# 修改域名
vim /etc/nginx/sites-available/pricing.conf
# 将 pricing.example.com 替换为实际域名

# 启用配置
ln -s /etc/nginx/sites-available/pricing.conf /etc/nginx/sites-enabled/

# 测试配置
nginx -t

# 重载 Nginx
nginx -s reload
```

#### 步骤 6：配置 SSL 证书

```bash
# 使用 Let's Encrypt
DOMAIN=pricing.yourcompany.com EMAIL=admin@yourcompany.com ./scripts/setup-ssl.sh request
```

### 2.3 升级部署

```bash
cd /opt/pricing-model

# 拉取最新代码
git pull

# 备份数据库（重要！）
./scripts/backup.sh backup

# 重新部署
./scripts/deploy.sh deploy
```

### 2.4 开发环境

```bash
# 使用开发配置
cp env.dev.example .env.dev

# 启动开发环境
docker-compose -f docker-compose.dev.yml up -d

# 访问
# 前端: http://localhost:3000 (热重载)
# 后端: http://localhost:8000
# API 文档: http://localhost:8000/docs
```

---

## 3. 配置管理

### 3.1 环境变量说明

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `APP_ENV` | 运行环境 | production |
| `DEBUG` | 调试模式 | false |
| `SECRET_KEY` | 应用密钥 | 必须配置 |
| `DATABASE_URL` | 数据库连接 | 必须配置 |
| `MYSQL_ROOT_PASSWORD` | MySQL root 密码 | 必须配置 |
| `MYSQL_USER` | MySQL 用户名 | pricing_user |
| `MYSQL_PASSWORD` | MySQL 密码 | 必须配置 |
| `PORTAL_CONFIG_API` | 门户系统 API | http://portal-backend:8000/api/ai/internal/config |
| `CORS_ORIGINS` | 允许的跨域来源 | ["https://pricing.example.com"] |
| `DB_POOL_SIZE` | 数据库连接池大小 | 5 |
| `DB_MAX_OVERFLOW` | 连接池溢出上限 | 10 |

### 3.2 Nginx 配置

主要配置项：

```nginx
# 域名
server_name pricing.yourcompany.com;

# SSL 证书路径
ssl_certificate     /etc/nginx/ssl/pricing.yourcompany.com.pem;
ssl_certificate_key /etc/nginx/ssl/pricing.yourcompany.com.key;

# 上传文件大小限制
client_max_body_size 10M;

# AI 接口超时（较长）
proxy_read_timeout 120s;
```

### 3.3 Docker 资源限制

```yaml
# docker-compose.yml 中的资源限制
deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M    # 后端
    reservations:
      cpus: '0.25'
      memory: 128M
```

建议配置：

| 服务 | 内存限制 | CPU 限制 |
|------|----------|----------|
| 前端 | 256M | 0.5 |
| 后端 | 512M | 1.0 |
| MySQL | 1G | 1.0 |

---

## 4. 日常运维

### 4.1 服务管理

```bash
# 查看服务状态
./scripts/deploy.sh status

# 重启所有服务
./scripts/deploy.sh restart

# 停止服务
./scripts/deploy.sh stop

# 查看日志
./scripts/deploy.sh logs

# 查看特定服务日志
docker-compose logs -f pricing-backend
docker-compose logs -f pricing-mysql
```

### 4.2 容器管理

```bash
# 进入后端容器
docker exec -it pricing-backend /bin/bash

# 进入 MySQL 容器
docker exec -it pricing-mysql mysql -u root -p

# 重启单个服务
docker-compose restart pricing-backend
```

### 4.3 数据库管理

```bash
# 连接数据库
docker exec -it pricing-mysql mysql -u root -p pricing_model

# 常用 SQL
-- 查看表
SHOW TABLES;

-- 查看项目数量
SELECT COUNT(*) FROM projects;

-- 查看最近操作日志
SELECT * FROM operation_logs ORDER BY created_at DESC LIMIT 10;
```

### 4.4 日志管理

日志位置：

```bash
# Docker 日志
/var/lib/docker/containers/<container_id>/<container_id>-json.log

# 查看日志大小
docker system df -v
```

清理日志：

```bash
# 清理停止的容器
docker container prune

# 清理未使用的镜像
docker image prune

# 清理所有未使用资源
docker system prune
```

---

## 5. 备份与恢复

### 5.1 自动备份

配置定时备份：

```bash
# 编辑 crontab
crontab -e

# 添加每日备份任务（每天凌晨 2 点）
0 2 * * * /opt/pricing-model/scripts/backup.sh backup >> /var/log/pricing-backup.log 2>&1
```

### 5.2 手动备份

```bash
# 执行备份
./scripts/backup.sh backup

# 查看备份列表
./scripts/backup.sh list

# 清理旧备份
./scripts/backup.sh cleanup
```

备份文件位置：`/data/backups/pricing_model/`

### 5.3 恢复数据

```bash
# 恢复指定备份
./scripts/backup.sh restore pricing_model_20260120_020000.sql.gz

# 或指定完整路径
./scripts/backup.sh restore /data/backups/pricing_model/pricing_model_20260120_020000.sql.gz
```

> **警告**：恢复操作会覆盖当前数据，请谨慎操作！

### 5.4 备份策略建议

| 备份类型 | 频率 | 保留期 |
|----------|------|--------|
| 数据库全量 | 每日 | 7 天 |
| 配置文件 | 变更时 | 长期 |
| 代码 | Git 管理 | 长期 |

---

## 6. 监控与告警

### 6.1 健康检查

```bash
# 运行监控检查
./scripts/monitor.sh report

# 快速检查（适合 cron）
./scripts/monitor.sh quick
```

### 6.2 监控指标

| 指标 | 检查方式 | 告警阈值 |
|------|----------|----------|
| 容器状态 | docker ps | 非 running |
| 健康检查 | /health API | 响应失败 |
| 磁盘使用 | df -h | > 80% 警告, > 90% 严重 |
| 内存使用 | free | > 80% 警告, > 90% 严重 |
| API 响应 | curl | > 2s 警告 |

### 6.3 配置定时监控

```bash
# 每 5 分钟检查一次
*/5 * * * * /opt/pricing-model/scripts/monitor.sh quick >> /var/log/pricing-monitor.log 2>&1
```

### 6.4 告警配置

编辑 `scripts/monitor.sh` 配置告警方式：

```bash
# 邮件告警
ALERT_EMAIL=admin@yourcompany.com

# 企业微信/钉钉 webhook
WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
```

---

## 7. 故障排查

### 7.1 服务无法启动

**检查步骤**：

```bash
# 1. 检查 Docker 服务
systemctl status docker

# 2. 检查容器日志
docker-compose logs pricing-backend
docker-compose logs pricing-mysql

# 3. 检查端口占用
netstat -tlnp | grep -E '8000|3306'

# 4. 检查磁盘空间
df -h
```

### 7.2 数据库连接失败

```bash
# 1. 检查 MySQL 容器状态
docker ps | grep pricing-mysql

# 2. 检查数据库日志
docker logs pricing-mysql

# 3. 测试数据库连接
docker exec pricing-mysql mysqladmin ping -h localhost

# 4. 检查 DATABASE_URL 配置
cat .env | grep DATABASE_URL
```

### 7.3 API 响应慢

```bash
# 1. 检查后端容器资源
docker stats pricing-backend

# 2. 检查数据库慢查询
docker exec -it pricing-mysql mysql -e "SHOW PROCESSLIST;"

# 3. 检查 AI 服务连接
curl -sf http://portal-backend:8000/api/ai/internal/config
```

### 7.4 前端页面空白

```bash
# 1. 检查前端容器
docker logs pricing-frontend

# 2. 检查 Nginx 配置
nginx -t

# 3. 检查静态文件
docker exec pricing-frontend ls -la /usr/share/nginx/html/
```

### 7.5 常见错误及解决

| 错误 | 可能原因 | 解决方案 |
|------|----------|----------|
| `Connection refused` | 服务未启动 | 重启服务 |
| `Access denied` | 数据库密码错误 | 检查 .env 配置 |
| `Network unreachable` | 网络配置错误 | 检查 Docker 网络 |
| `No space left` | 磁盘满 | 清理日志/扩容 |
| `Out of memory` | 内存不足 | 增加内存/优化限制 |

---

## 8. 安全规范

### 8.1 敏感信息管理

- `.env` 文件权限必须为 600
- 禁止将 `.env` 提交到 Git
- 定期轮换数据库密码
- API Key 从门户系统获取，禁止硬编码

### 8.2 网络安全

- 仅 Nginx 暴露公网端口（80/443）
- 后端服务仅内网访问
- 数据库端口禁止外部访问
- 启用 HTTPS，HTTP 自动重定向

### 8.3 访问控制

- 使用 OAuth 统一认证
- 敏感操作记录审计日志
- 定期审查用户权限

### 8.4 安全检查清单

- [ ] .env 文件权限为 600
- [ ] 已修改默认密码
- [ ] SECRET_KEY 使用随机字符串
- [ ] HTTPS 已启用
- [ ] 数据库端口未暴露公网
- [ ] 定期备份已配置
- [ ] 监控告警已启用

---

## 9. 附录

### 9.1 目录结构

```
/opt/pricing-model/
├── 后端服务/              # 后端代码
├── 前端应用/              # 前端代码
├── scripts/              # 运维脚本
│   ├── deploy.sh        # 部署脚本
│   ├── backup.sh        # 备份脚本
│   ├── setup-ssl.sh     # SSL 配置
│   └── monitor.sh       # 监控脚本
├── docs/                 # 文档
├── docker-compose.yml    # 生产环境配置
├── docker-compose.dev.yml# 开发环境配置
├── nginx.conf            # Nginx 配置
├── init.sql              # 数据库初始化
├── .env                  # 环境变量（不提交）
└── .env.example          # 环境变量模板
```

### 9.2 端口说明

| 端口 | 服务 | 说明 |
|------|------|------|
| 80 | Nginx | HTTP（重定向到 HTTPS） |
| 443 | Nginx | HTTPS |
| 8000 | 后端 | API 服务（内网） |
| 3306 | MySQL | 数据库（内网） |

### 9.3 常用命令速查

```bash
# 部署
./scripts/deploy.sh deploy

# 重启
./scripts/deploy.sh restart

# 查看日志
./scripts/deploy.sh logs

# 备份
./scripts/backup.sh backup

# 监控
./scripts/monitor.sh report

# 进入容器
docker exec -it pricing-backend /bin/bash
docker exec -it pricing-mysql mysql -u root -p
```

### 9.4 相关文档

- 《瑞小美系统技术栈标准与字符标准》
- 《瑞小美 AI 接入规范》
- 《智能项目定价模型 - 产品需求文档》
- 《智能项目定价模型 - API 接口文档》

---

## 技术支持

如遇问题，请联系瑞小美技术团队。

---

*瑞小美技术团队 · 2026-01-20*