13 KiB
13 KiB
智能项目定价模型 - 系统管理手册
版本：v1.0
更新日期：2026-01-20
适用对象：系统管理员、运维人员
目录
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：获取代码
git clone <repository_url> /opt/pricing-model
cd /opt/pricing-model
步骤 2：配置环境变量
# 复制配置模板
cp env.example .env
# 编辑配置（修改数据库密码、密钥等）
vim .env
# 设置文件权限（重要！）
chmod 600 .env
必须修改的配置项：
# 数据库密码（请使用强密码）
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：创建外部网络
# 如果 scrm_network 不存在
docker network create scrm_network
步骤 4：执行部署
./scripts/deploy.sh deploy
步骤 5：配置 Nginx 反向代理
将 nginx.conf 添加到主机 Nginx 配置：
# 复制配置到 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 证书
# 使用 Let's Encrypt
DOMAIN=pricing.yourcompany.com EMAIL=admin@yourcompany.com ./scripts/setup-ssl.sh request
2.3 升级部署
cd /opt/pricing-model
# 拉取最新代码
git pull
# 备份数据库（重要！）
./scripts/backup.sh backup
# 重新部署
./scripts/deploy.sh deploy
2.4 开发环境
# 使用开发配置
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 配置
主要配置项：
# 域名
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 资源限制
# 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 服务管理
# 查看服务状态
./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 容器管理
# 进入后端容器
docker exec -it pricing-backend /bin/bash
# 进入 MySQL 容器
docker exec -it pricing-mysql mysql -u root -p
# 重启单个服务
docker-compose restart pricing-backend
4.3 数据库管理
# 连接数据库
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 日志管理
日志位置：
# Docker 日志
/var/lib/docker/containers/<container_id>/<container_id>-json.log
# 查看日志大小
docker system df -v
清理日志：
# 清理停止的容器
docker container prune
# 清理未使用的镜像
docker image prune
# 清理所有未使用资源
docker system prune
5. 备份与恢复
5.1 自动备份
配置定时备份：
# 编辑 crontab
crontab -e
# 添加每日备份任务（每天凌晨 2 点）
0 2 * * * /opt/pricing-model/scripts/backup.sh backup >> /var/log/pricing-backup.log 2>&1
5.2 手动备份
# 执行备份
./scripts/backup.sh backup
# 查看备份列表
./scripts/backup.sh list
# 清理旧备份
./scripts/backup.sh cleanup
备份文件位置：/data/backups/pricing_model/
5.3 恢复数据
# 恢复指定备份
./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 健康检查
# 运行监控检查
./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 配置定时监控
# 每 5 分钟检查一次
*/5 * * * * /opt/pricing-model/scripts/monitor.sh quick >> /var/log/pricing-monitor.log 2>&1
6.4 告警配置
编辑 scripts/monitor.sh 配置告警方式：
# 邮件告警
ALERT_EMAIL=admin@yourcompany.com
# 企业微信/钉钉 webhook
WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
7. 故障排查
7.1 服务无法启动
检查步骤：
# 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 数据库连接失败
# 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 响应慢
# 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 前端页面空白
# 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 常用命令速查
# 部署
./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