kuzma/smart-project-pricing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: 智能项目定价模型

Browse Source
This commit is contained in:
kuzma
2026-01-31 21:33:06 +08:00
commit ef0824303f
174 changed files with 31705 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

620
docs/系统管理手册.md Normal file
View File

@@ -0,0 +1,620 @@
# 智能项目定价模型 - 系统管理手册
> **版本**：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*