docs: 移动蓝绿部署指南到 troubleshooting 目录
This commit is contained in:
Simon
+118
-62
@@ -43,65 +43,63 @@
|
||||
```
|
||||
|
||||
> **OpenSSH `ssh -J` 方式不再使用**(用户已确认用 PuTTY,2026-06-15)
|
||||
# 登录成功后：
|
||||
ssh sxn@10.90.5.110
|
||||
```
|
||||
|
||||
### 2.3 配置 SSH 快捷方式（推荐）
|
||||
### 2.3 jumpserver-ops 工具（推荐）
|
||||
|
||||
在开发机上编辑 `~/.ssh/config`，添加以下内容，以后只需要 `ssh itdesk` 即可：
|
||||
推荐使用 jumpserver-ops 工具进行远程命令执行和文件传输。该工具自动化完成 JumpServer 登录、OTP 验证、资产连接等全流程。
|
||||
|
||||
```
|
||||
# 堡垒机
|
||||
Host bastion
|
||||
HostName 10.212.189.210
|
||||
Port 2222
|
||||
User sxn
|
||||
|
||||
# 智能IT支持服务台服务器
|
||||
Host itdesk
|
||||
HostName 10.90.5.110
|
||||
User sxn
|
||||
ProxyJump bastion
|
||||
```
|
||||
|
||||
> **堡垒机用户名为 `sxn`，已填入下方命令中**
|
||||
|
||||
之后只需：
|
||||
```bash
|
||||
ssh itdesk # 自动通过堡垒机跳转
|
||||
scp file itdesk:/opt/ # 文件传输也会自动走堡垒机
|
||||
# 进入 skill 目录
|
||||
cd C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts
|
||||
|
||||
# 远程执行命令（首次登录约 13s，后续复用约 2-3s）
|
||||
python jms_ops.py exec -c "hostname"
|
||||
python jms_ops.py exec -c "uptime" -c "docker ps"
|
||||
|
||||
# 文件上传（自动选择最优方式：<100KB 用 base64，>=100KB 或 >15s 用 elFinder）
|
||||
python jms_ops.py upload local_file.txt /tmp/remote_file.txt
|
||||
|
||||
# 文件下载（base64 通道）
|
||||
python jms_ops.py download /tmp/server_file.txt ./local_file.txt
|
||||
```
|
||||
|
||||
> **注意**：首次使用会弹出浏览器完成 JumpServer 登录和 OTP 验证，后续调用会自动复用会话（30分钟内有效）。
|
||||
|
||||
### 2.4 为什么不能直接用 SSH/SCP？
|
||||
|
||||
| 方式 | 支持情况 | 原因 |
|
||||
|------|---------|------|
|
||||
| SSH ProxyJump | ❌ 不支持 | JumpServer 不兼容标准 SSH 代理协议 |
|
||||
| SCP 直连堡垒机 | ❌ 不支持 | 需要 OTP 验证码，SCP 不支持交互式输入 |
|
||||
| SSH 直连目标服务器 | ❌ 不支持 | 目标服务器仅对 JumpServer 开放 SSH 访问 |
|
||||
| jumpserver-ops | ✅ 推荐 | 自动化处理 OTP 和 Connection Token |
|
||||
|
||||
---
|
||||
|
||||
## 三、文件传输（通过堡垒机）
|
||||
|
||||
### 3.1 SCP 传输（推荐小文件/单次传输）
|
||||
### 3.1 jumpserver-ops 上传（推荐）
|
||||
|
||||
```bash
|
||||
# 上传单个文件
|
||||
scp -o "ProxyJump=sxn@10.212.189.210:2222" \
|
||||
it-smart-desk-server-deploy.zip \
|
||||
sxn@10.90.5.110:/opt/
|
||||
# 上传文件到目标服务器 /tmp 目录
|
||||
# 自动选择最优方式：<100KB 用 base64（快），>=100KB 或 >15s 用 elFinder（稳定）
|
||||
python jms_ops.py upload deploy.zip /tmp/deploy.zip
|
||||
|
||||
# 如果已配置 ~/.ssh/config：
|
||||
scp it-smart-desk-server-deploy.zip itdesk:/opt/
|
||||
# 上传到其他目录
|
||||
python jms_ops.py upload config.conf /opt/wecom-it-desk/config.conf
|
||||
```
|
||||
|
||||
### 3.2 大文件传输优化
|
||||
### 3.2 备用方案
|
||||
|
||||
部署包可能较大（含后端源码 + 前端产物），如果 SCP 速度慢，可以先传到堡垒机再转：
|
||||
如果 jumpserver-ops 不可用，可以考虑：
|
||||
|
||||
```bash
|
||||
# 步骤1：传到堡垒机
|
||||
scp -P 2222 it-smart-desk-server-deploy.zip sxn@10.212.189.210:/tmp/
|
||||
# 方式A：通过互联网可访问的存储服务（推荐）
|
||||
# - 先把文件传到能通过互联网访问的存储（如：对象存储、临时文件分享服务）
|
||||
# - 目标服务器通过 curl/wget 下载
|
||||
|
||||
# 步骤2：SSH 到堡垒机
|
||||
ssh -p 2222 sxn@10.212.189.210
|
||||
|
||||
# 步骤3：从堡垒机传到目标服务器
|
||||
scp /tmp/it-smart-desk-server-deploy.zip sxn@10.90.5.110:/opt/
|
||||
# 方式B：通过堡垒机手动中转
|
||||
# - 使用 jumpserver-ops 手动执行分步操作
|
||||
```
|
||||
|
||||
---
|
||||
@@ -276,28 +274,86 @@ DNS 生效后（或配置了本地 hosts），在浏览器中访问：
|
||||
|
||||
## 五、部署文件结构
|
||||
|
||||
### 5.1 服务器目录结构
|
||||
|
||||
```
|
||||
/opt/wecom-it-desk/
|
||||
├── docker-compose.yml # Docker Compose 配置（4容器）
|
||||
├── .env # 环境变量（已配置）
|
||||
├── .env.example # 环境变量模板
|
||||
├── deploy.sh # 一键部署脚本
|
||||
├── README.md # 本手册
|
||||
/opt/wecom-it-desk/ # 项目根目录（服务器）
|
||||
├── docker-compose.yml # Docker Compose 配置（4容器）
|
||||
├── .env # 环境变量（已配置）
|
||||
├── .env.example # 环境变量模板
|
||||
├── deploy.sh # 一键部署脚本
|
||||
├── nginx/
|
||||
│ └── nginx.conf # Nginx 配置（反代 + 静态文件）
|
||||
├── backend/
|
||||
│ ├── Dockerfile # 后端镜像构建文件
|
||||
│ ├── requirements.txt # Python 依赖
|
||||
│ └── app/ # 后端源代码
|
||||
├── frontend-h5/
|
||||
│ └── dist/ # H5 员工端构建产物
|
||||
└── frontend-agent/
|
||||
└── dist/ # 坐席工作台构建产物
|
||||
│ ├── nginx.conf # Nginx 配置（反代 + 静态文件）
|
||||
│ └── ssl/ # SSL 证书
|
||||
├── html/ # 前端静态文件（Nginx 挂载点）
|
||||
│ ├── itdesk/ # H5 员工端 (/itdesk/)
|
||||
│ ├── itagent/ # 坐席工作台 (/itagent/)
|
||||
│ ├── itadmin/ # 管理后台 (/itadmin/)
|
||||
│ └── itportal/ # 统一入口 (/itportal/)
|
||||
└── backend/ # 后端源码（不用于生产，仅开发参考）
|
||||
```
|
||||
|
||||
### 5.2 前端部署位置说明
|
||||
|
||||
| 端 | URL 路径 | 服务器目录 | Nginx 容器挂载点 |
|
||||
|----|---------|-----------|----------------|
|
||||
| 员工端 H5 | `/itdesk/` | `/opt/wecom-it-desk/html/itdesk/` | `/usr/share/nginx/html/itdesk` |
|
||||
| 坐席工作台 | `/itagent/` | `/opt/wecom-it-desk/html/itagent/` | `/usr/share/nginx/html/itagent` |
|
||||
| 管理后台 | `/itadmin/` | `/opt/wecom-it-desk/html/itadmin/` | `/usr/share/nginx/html/itadmin` |
|
||||
| 统一入口 | `/itportal/` | `/opt/wecom-it-desk/html/itportal/` | `/usr/share/nginx/html/itportal` |
|
||||
|
||||
### 5.3 前端部署步骤
|
||||
|
||||
```bash
|
||||
# 1. 本地构建
|
||||
cd frontend-agent
|
||||
npm run build
|
||||
|
||||
# 2. 打包（排除 node_modules）
|
||||
cd dist
|
||||
zip -r ../agent-v1.x.zip *
|
||||
|
||||
# 3. 上传到服务器 /tmp/
|
||||
# 4. SSH 到服务器解压
|
||||
sudo rm -rf /opt/wecom-it-desk/html/itagent
|
||||
sudo mkdir -p /opt/wecom-it-desk/html/itagent
|
||||
sudo unzip -o /tmp/agent-v1.x.zip -d /opt/wecom-it-desk/html/itagent
|
||||
|
||||
# 5. 重启 Nginx 容器
|
||||
docker restart wecom_it_nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、常用运维命令
|
||||
## 六、Python 依赖管理
|
||||
|
||||
### 6.1 依赖说明
|
||||
|
||||
后端 Python 依赖在 `backend/requirements.txt` 中声明，构建 Docker 镜像时会自动安装。
|
||||
|
||||
**新增依赖处理流程：**
|
||||
|
||||
1. **开发环境**：更新 `backend/requirements.txt`
|
||||
2. **打包部署**：确保 `requirements.txt` 已包含新依赖
|
||||
3. **生产环境**：重建后端镜像
|
||||
|
||||
```bash
|
||||
# 重建后端镜像（会自动安装 requirements.txt 中的所有依赖）
|
||||
cd /opt/wecom-it-desk
|
||||
docker compose build backend
|
||||
docker compose up -d backend
|
||||
```
|
||||
|
||||
### 6.2 常见依赖问题
|
||||
|
||||
| 问题 | 症状 | 解决方法 |
|
||||
|------|------|---------|
|
||||
| 缺少依赖 | `ModuleNotFoundError` | 重建后端镜像：`docker compose build backend` |
|
||||
| 手动安装 | 容器内临时安装 | `docker exec wecom_it_backend pip install <package>` |
|
||||
|
||||
---
|
||||
|
||||
## 七、常用运维命令
|
||||
|
||||
在服务器上 `/opt/wecom-it-desk` 目录下执行：
|
||||
|
||||
@@ -318,7 +374,7 @@ DNS 生效后（或配置了本地 hosts），在浏览器中访问：
|
||||
|
||||
---
|
||||
|
||||
## 七、升级前端
|
||||
## 八、升级前端
|
||||
|
||||
当有新的前端版本需要部署时：
|
||||
|
||||
@@ -344,7 +400,7 @@ docker exec wecom_it_nginx nginx -s reload
|
||||
|
||||
---
|
||||
|
||||
## 八、升级后端
|
||||
## 九、升级后端
|
||||
|
||||
```bash
|
||||
# 1. 上传新代码到服务器
|
||||
@@ -360,7 +416,7 @@ cd /opt/wecom-it-desk
|
||||
|
||||
---
|
||||
|
||||
## 九、故障排查
|
||||
## 十、故障排查
|
||||
|
||||
### 后端容器一直重启
|
||||
|
||||
@@ -427,7 +483,7 @@ curl -X POST http://localhost/api/h5/mock-login \
|
||||
|
||||
---
|
||||
|
||||
## 十、HTTPS 配置（可选）
|
||||
## 十一、HTTPS 配置（可选）
|
||||
|
||||
如果公司要求 HTTPS，有两种方式：
|
||||
|
||||
@@ -445,7 +501,7 @@ curl -X POST http://localhost/api/h5/mock-login \
|
||||
|
||||
---
|
||||
|
||||
## 十一、部署说明
|
||||
## 十二、部署说明
|
||||
|
||||
> ⚠️ NAS部署方案（itdesk.amanzac.com）已于2026年6月15日下线，现统一使用公司内网服务器部署。
|
||||
|
||||
@@ -461,7 +517,7 @@ curl -X POST http://localhost/api/h5/mock-login \
|
||||
|
||||
---
|
||||
|
||||
## 十二、相关文档
|
||||
## 十三、相关文档
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
|
||||
Reference in New Issue
Block a user