Simon
228 lines
7.1 KiB
Markdown
228 lines
7.1 KiB
Markdown
# 企微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
|
||
```
|