chore(docs): docs/ 目录全面重新编号 + 重组
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
This commit is contained in:
Simon
@@ -0,0 +1,227 @@
|
||||
# 企微智能IT支持服务台 — 远程服务器部署指南（预生产）
|
||||
|
||||
> **预生产环境**：本系统与 IT 数据查询平台部署在**不同主机**。正式环境将迁移到 K8s。
|
||||
|
||||
## 部署架构
|
||||
|
||||
```
|
||||
浏览器 ──→ it-dataquery.dc.servyou-it.com:80
|
||||
│
|
||||
▼
|
||||
┌─── nginx (本系统主机) ──────────────────────┐
|
||||
│ │
|
||||
│ /itdesk/* → H5 员工端 SPA │
|
||||
│ /itagent/* → 坐席工作台 SPA │
|
||||
│ /api/* → backend:8000 (FastAPI) │
|
||||
│ /ws/* → backend:8000 (WebSocket) │
|
||||
│ /* → 远程代理到数据平台主机 IP │ ← 跨主机
|
||||
│ │
|
||||
└──────────────┬─────────────────────────────┘
|
||||
│ 本机 Docker 网络
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ backend │ │ postgres │ │ redis │
|
||||
│ :8000 │ │ :5432 │ │ :6379 │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
## 网络互联
|
||||
|
||||
预生产环境中，数据平台在独立主机，**不需要 Docker 网络互联**。Nginx 通过远程 IP 直接反代数据平台：
|
||||
|
||||
```
|
||||
本系统主机 (Docker) 数据平台主机
|
||||
┌──────────────────┐ ┌─────────────────┐
|
||||
│ nginx ──────────┼── HTTP 反代 ──→ │ 数据平台 :80 │
|
||||
│ │ │ 远程 IP │ │
|
||||
│ ▼ │ └─────────────────┘
|
||||
│ backend:8000 │
|
||||
│ postgres:5432 │
|
||||
│ redis:6379 │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 服务器已安装 Docker + Docker Compose
|
||||
- IT 数据查询平台已部署运行
|
||||
- 有 SSH 登录权限
|
||||
|
||||
## 部署步骤
|
||||
|
||||
### 1. 配置数据平台反代地址
|
||||
|
||||
预生产环境中，数据平台在**独立主机**。部署前，必须将 nginx 配置中的数据平台上游地址改为实际 IP。
|
||||
|
||||
编辑 `nginx/nginx.conf`：
|
||||
|
||||
```nginx
|
||||
# 将 DATAQUERY_HOST 替换为数据平台主机的实际 IP:端口
|
||||
upstream dataquery {
|
||||
server 10.80.0.86:80; # ← 改为数据平台实际 IP
|
||||
}
|
||||
```
|
||||
|
||||
> 不再需要创建 `it-platform-net` —— Docker 网络无法跨主机互联。nginx 通过 HTTP 直接反代到远程 IP。
|
||||
|
||||
### 3. 上传部署包
|
||||
|
||||
在本地（Windows）执行：
|
||||
|
||||
```bash
|
||||
# 方式 A：使用 deploy.sh 打包
|
||||
bash scripts/deploy.sh --pack
|
||||
scp it-smart-desk-*.tar.gz user@server:/opt/
|
||||
|
||||
# 方式 B：手动打包
|
||||
tar czf deploy.tar.gz \
|
||||
backend/ frontend-h5/dist/ frontend-agent/dist/ \
|
||||
nginx/ docker-compose.yml .env.production scripts/
|
||||
scp deploy.tar.gz user@server:/opt/it-smart-desk/
|
||||
```
|
||||
|
||||
### 4. 服务器上解压和配置
|
||||
|
||||
```bash
|
||||
ssh user@server
|
||||
cd /opt/it-smart-desk
|
||||
tar xzf it-smart-desk-*.tar.gz
|
||||
|
||||
# 创建环境配置（填入真实企微凭证）
|
||||
cp .env.production .env
|
||||
vim .env
|
||||
```
|
||||
|
||||
`.env` 必填项：
|
||||
|
||||
| 配置项 | 说明 | 获取位置 |
|
||||
|--------|------|---------|
|
||||
| `WECOM_CORP_ID` | 企业ID | 企微管理后台 > 我的企业 |
|
||||
| `WECOM_AGENT_ID` | 应用AgentId | 企微管理后台 > 应用管理 |
|
||||
| `WECOM_SECRET` | 应用Secret | 企微管理后台 > 应用管理 |
|
||||
| `WECOM_TOKEN` | 回调Token | 企微管理后台 > 接收消息 |
|
||||
| `WECOM_ENCODING_AES_KEY` | 回调AES密钥 | 企微管理后台 > 接收消息 |
|
||||
| `POSTGRES_PASSWORD` | 数据库密码 | 自定义强密码 |
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
```bash
|
||||
bash scripts/deploy.sh
|
||||
```
|
||||
|
||||
这会自动执行：检查前置条件 → 构建后端镜像 → 启动所有容器
|
||||
|
||||
### 6. 验证部署
|
||||
|
||||
```bash
|
||||
# 检查容器状态
|
||||
docker compose ps
|
||||
|
||||
# 健康检查
|
||||
curl http://localhost:18080/itdesk/health
|
||||
|
||||
# 查看 H5 员工端
|
||||
curl -I http://localhost:18080/itdesk/
|
||||
|
||||
# 查看坐席工作台
|
||||
curl -I http://localhost:18080/itagent/
|
||||
|
||||
# 查看后端 API
|
||||
curl http://localhost:18080/api/docs
|
||||
```
|
||||
|
||||
浏览器验证：
|
||||
|
||||
| 地址 | 预期 |
|
||||
|------|------|
|
||||
| `http://it-dataquery.dc.servyou-it.com/itdesk/` | H5 员工咨询页面 |
|
||||
| `http://it-dataquery.dc.servyou-it.com/itagent/` | 坐席工作台登录页 |
|
||||
| `http://it-dataquery.dc.servyou-it.com/` | IT 数据查询平台（不变） |
|
||||
| `http://it-dataquery.dc.servyou-it.com/api/docs` | FastAPI Swagger 文档 |
|
||||
|
||||
## 两种网络接入方式
|
||||
|
||||
### 方式 A：数据平台 nginx 反代到本项目 nginx（推荐）
|
||||
|
||||
数据平台的 nginx 配置添加：
|
||||
|
||||
```nginx
|
||||
# IT 智能服务台路由
|
||||
location /itdesk/ {
|
||||
proxy_pass http://wecom_it_nginx:80/itdesk/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
location /itagent/ {
|
||||
proxy_pass http://wecom_it_nginx:80/itagent/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
location /api/ {
|
||||
proxy_pass http://wecom_it_nginx:80/api/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
location /ws/ {
|
||||
proxy_pass http://wecom_it_nginx:80/ws/;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
```
|
||||
|
||||
此方式下本项目 nginx 不暴露 80 端口，docker-compose.yml 的 `ports` 可以删除。
|
||||
|
||||
### 方式 B：本项目 nginx 直接监听 80 端口
|
||||
|
||||
如果数据平台没有自己的 nginx，或者想用本项目的 nginx 统一管理：
|
||||
|
||||
1. 停止数据平台的端口映射
|
||||
2. 本项目 nginx 的 80 端口直接对外
|
||||
3. nginx.conf 中的 `location /` 反代到数据平台容器
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: nginx 启动失败，报 `host not found in upstream "dataquery"`
|
||||
A: `nginx/nginx.conf` 中的 `DATAQUERY_HOST` 未替换为数据平台实际 IP。编辑 nginx.conf，将占位符改为实际 IP:端口。
|
||||
|
||||
### Q: 访问 /itdesk/ 返回 404
|
||||
A: 检查前端 dist 是否正确挂载：
|
||||
```bash
|
||||
docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itdesk/
|
||||
```
|
||||
|
||||
### Q: API 返回 CORS 错误
|
||||
A: 检查 `.env` 中的 `CORS_ORIGINS` 是否包含 `http://it-dataquery.dc.servyou-it.com`
|
||||
|
||||
### Q: 数据库迁移失败
|
||||
A: 查看 backend 日志：
|
||||
```bash
|
||||
docker compose logs backend
|
||||
```
|
||||
如果 PostgreSQL 未就绪，等 30 秒后重启 backend：
|
||||
```bash
|
||||
docker compose restart backend
|
||||
```
|
||||
|
||||
## 更新部署
|
||||
|
||||
只需更新变更的部分：
|
||||
|
||||
```bash
|
||||
# 仅更新前端
|
||||
bash scripts/deploy.sh --build
|
||||
docker compose restart nginx
|
||||
|
||||
# 仅更新后端
|
||||
docker compose build backend
|
||||
docker compose up -d backend
|
||||
|
||||
# 全量更新
|
||||
bash scripts/deploy.sh --down
|
||||
bash scripts/deploy.sh
|
||||
```
|
||||
Reference in New Issue
Block a user