Files

T

Simon 63262292d7 chore: initial baseline with P0-safety .gitignore

2026-06-14 16:51:56 +08:00

12 KiB

Raw Permalink Blame History

IT智能服务台 — 新服务器部署手册

目标服务器：10.80.0.136（公司内网）域名：itsupport.servyou.com.cn 访问方式：通过堡垒机 10.212.189.210:2222（用户 sxn，OTP 动态口令认证） Docker：已安装 部署方式：Docker Compose（4容器：nginx + backend + postgres + redis）

一、前置条件检查清单

条件	状态	验证命令
Linux 服务器 10.80.0.136	✅ 已确认	—
Docker 已安装	✅ 已确认	`docker --version`
Docker Compose V2	待确认	`docker compose version`
端口 80 未被占用	待确认	`ss -tlnp \| grep :80`
DNS 解析	待配置	`nslookup itsupport.servyou.com.cn`
堡垒机可访问	待确认	`ssh -p 2222 user@10.212.189.210`

二、SSH 通过堡垒机连接

2.1 什么是堡垒机？

堡垒机（跳板机）是公司内网的安全访问入口。你不能直接 SSH 到目标服务器，必须先登录堡垒机，再从堡垒机跳转到目标服务器。OTP（One-Time Password）是指每次登录需要输入动态验证码（通常来自手机令牌 App）。

2.2 连接方式

# 方式一：ssh -J 一步跳转（推荐）
# -J 指定跳板机，ssh 会自动帮你跳转
# 堡垒机端口 2222，需要输入 OTP 动态口令
ssh -J sxn@10.212.189.210:2222 sxn@10.80.0.136

# 方式二：先登录堡垒机，再手动跳转
ssh -p 2222 sxn@10.212.189.210
# 输入 OTP 动态口令
# 登录成功后：
ssh sxn@10.80.0.136

2.3 配置 SSH 快捷方式（推荐）

在开发机上编辑 ~/.ssh/config，添加以下内容，以后只需要 ssh itdesk 即可：

# 堡垒机
Host bastion
    HostName 10.212.189.210
    Port 2222
    User sxn

# IT智能服务台服务器
Host itdesk
    HostName 10.80.0.136
    User sxn
    ProxyJump bastion

堡垒机用户名为 sxn，已填入下方命令中

之后只需：

ssh itdesk          # 自动通过堡垒机跳转
scp file itdesk:/opt/  # 文件传输也会自动走堡垒机

三、文件传输（通过堡垒机）

3.1 SCP 传输（推荐小文件/单次传输）

# 上传单个文件
scp -o "ProxyJump=sxn@10.212.189.210:2222" \
    it-smart-desk-server-deploy.zip \
    sxn@10.80.0.136:/opt/

# 如果已配置 ~/.ssh/config：
scp it-smart-desk-server-deploy.zip itdesk:/opt/

3.2 大文件传输优化

部署包可能较大（含后端源码 + 前端产物），如果 SCP 速度慢，可以先传到堡垒机再转：

# 步骤1：传到堡垒机
scp -P 2222 it-smart-desk-server-deploy.zip sxn@10.212.189.210:/tmp/

# 步骤2：SSH 到堡垒机
ssh -p 2222 sxn@10.212.189.210

# 步骤3：从堡垒机传到目标服务器
scp /tmp/it-smart-desk-server-deploy.zip sxn@10.80.0.136:/opt/

四、部署步骤（完整流程）

步骤 1：在开发机上构建前端并打包

# 在开发机（Windows）上，进入项目根目录
cd D:\资料\03-项目开发\wecom_it_smart_desk

# 方法A：使用打包脚本（自动构建前端 + 组装 + 打包）
bash deploy-server/package.sh

# 方法B：手动构建
# H5 员工端
cd frontend-h5
npm install && npm run build

# 坐席工作台
cd ../frontend-agent
npm install && npm run build

# 手动打包（如果不用 package.sh）
# 需要把 frontend-h5/dist/、frontend-agent/dist/、backend/、deploy-server/ 下的配置文件一起打包

打包完成后，项目根目录下会生成 it-smart-desk-server-deploy.zip。

步骤 2：上传部署包到服务器

# 在开发机上执行
scp -o "ProxyJump=sxn@10.212.189.210:2222" \
    it-smart-desk-server-deploy.zip \
    sxn@10.80.0.136:/tmp/

上传到 /tmp/ 而非 /opt/，因为普通用户对 /opt/ 没有写权限

步骤 3：SSH 登录服务器并解压

# 登录目标服务器
ssh -J sxn@10.212.189.210:2222 sxn@10.80.0.136

# 切换 root（普通用户对 /opt 无写权限）
sudo -i

# 移动并解压部署包
mv /tmp/it-smart-desk-server-deploy.zip /opt/
cd /opt
unzip it-smart-desk-server-deploy.zip

# 重命名目录为更简短的名称
mv it-smart-desk-server-deploy wecom-it-desk
cd wecom-it-desk

步骤 4：配置环境变量

cd /opt/wecom-it-desk

# 从模板创建 .env
cp .env.example .env

# 编辑 .env
vi .env

阶段一（Mock 模式）最小配置 — 只需确认以下默认值：

# 数据库密码（默认即可，首次初始化后不可更改）
POSTGRES_PASSWORD=wecom_secret_2024

# 企微配置（阶段一 Mock 模式可以留空）
WECOM_CORP_ID=
WECOM_AGENT_ID=1000002
WECOM_SECRET=
WECOM_TOKEN=
WECOM_ENCODING_AES_KEY=

# Mock 登录（阶段一设为 true）
MOCK_LOGIN_ENABLED=true

# Dify AI（暂时可以留空）
DIFY_API_URL=http://yw-dify.dc.servyou-it.com/dify2openai/v1/chat/completions
DIFY_API_KEY=

重要：POSTGRES_PASSWORD 首次启动时写入数据库，之后修改 .env 不会生效。如需修改密码，必须删除数据卷重建。

步骤 5：部署

cd /opt/wecom-it-desk

# 添加执行权限
chmod +x deploy.sh

# 执行部署
./deploy.sh

脚本会自动：

✅ 检查 Docker 环境
✅ 检查 .env 配置
✅ 检查前端文件
✅ 构建后端 Docker 镜像
✅ 启动 4 个容器
✅ 等待服务就绪
✅ 验证部署

步骤 6：验证部署

# 在服务器上验证
curl http://localhost/api/health
# 应返回 {"status":"healthy"}

curl http://localhost/itdesk/
# 应返回 H5 前端 HTML

# 查看所有容器状态
docker compose ps
# 应显示 4 个容器都是 Up 状态

# 如果有容器未启动，查看日志
docker compose logs --tail 50 backend
docker compose logs --tail 50 postgres

步骤 7：配置 DNS

需要联系公司 IT 运维，在公司 DNS 上添加 A 记录：

itsupport.servyou.com.cn  A  10.80.0.136

DNS 未生效前，可以通过本地 hosts 文件测试：

# Windows: C:\Windows\System32\drivers\etc\hosts
# macOS/Linux: /etc/hosts
# 添加一行：
10.80.0.136  itsupport.servyou.com.cn

注意：修改 hosts 文件后，浏览器可能有 DNS 缓存。Chrome 可访问 chrome://net-internals/#dns 清除缓存，或用无痕窗口测试。

步骤 8：浏览器验证

DNS 生效后（或配置了本地 hosts），在浏览器中访问：

页面	URL	预期结果
H5 员工端	`http://itsupport.servyou.com.cn/itdesk/`	看到登录页面
坐席工作台	`http://itsupport.servyou.com.cn/itagent/`	看到坐席工作台
API 健康检查	`http://itsupport.servyou.com.cn/api/health`	`{"status":"healthy"}`

Mock 登录测试：

访问 http://itsupport.servyou.com.cn/itdesk/login
输入任意工号和姓名（如 test001 / 测试用户）
应成功登录并进入聊天页面

五、部署文件结构

/opt/wecom-it-desk/
├── docker-compose.yml     # Docker Compose 配置（4容器）
├── .env                   # 环境变量（已配置）
├── .env.example           # 环境变量模板
├── deploy.sh              # 一键部署脚本
├── README.md              # 本手册
├── nginx/
│   └── nginx.conf         # Nginx 配置（反代 + 静态文件）
├── backend/
│   ├── Dockerfile          # 后端镜像构建文件
│   ├── requirements.txt    # Python 依赖
│   └── app/               # 后端源代码
├── frontend-h5/
│   └── dist/              # H5 员工端构建产物
└── frontend-agent/
    └── dist/              # 坐席工作台构建产物

六、常用运维命令

在服务器上 /opt/wecom-it-desk 目录下执行：

操作	命令
查看服务状态	`./deploy.sh status`
查看后端日志	`./deploy.sh logs`
停止所有服务	`./deploy.sh stop`
重新构建后端	`./deploy.sh rebuild`
重置数据库	`./deploy.sh reset-db`
手动启动	`docker compose up -d`
手动停止	`docker compose down`
只重启后端	`docker compose restart backend`
查看数据库	`docker exec -it wecom_it_postgres psql -U wecom -d wecom_it_desk`
查看 Redis	`docker exec -it wecom_it_redis redis-cli`
重载 Nginx	`docker exec wecom_it_nginx nginx -s reload`
查看容器日志	`docker compose logs --tail 50 <容器名>`

七、升级前端

当有新的前端版本需要部署时：

# 1. 在开发机上构建新版本
cd frontend-h5 && npm run build
cd frontend-agent && npm run build

# 2. 上传到服务器（通过堡垒机）
scp -o "ProxyJump=sxn@10.212.189.210:2222" \
    -r frontend-h5/dist/ \
    sxn@10.80.0.136:/opt/wecom-it-desk/frontend-h5/dist/

scp -o "ProxyJump=sxn@10.212.189.210:2222" \
    -r frontend-agent/dist/ \
    sxn@10.80.0.136:/opt/wecom-it-desk/frontend-agent/dist/

# 3. 重载 Nginx（不需要重启整个服务）
ssh itdesk  # 如果已配置 SSH 快捷方式
cd /opt/wecom-it-desk
docker exec wecom_it_nginx nginx -s reload

八、升级后端

# 1. 上传新代码到服务器
scp -o "ProxyJump=sxn@10.212.189.210:2222" \
    -r backend/ \
    sxn@10.80.0.136:/opt/wecom-it-desk/backend/

# 2. 重新构建并启动
ssh itdesk
cd /opt/wecom-it-desk
./deploy.sh rebuild

九、故障排查

后端容器一直重启

# 1. 查看容器状态
docker compose ps

# 2. 查看后端日志（最常见原因：数据库连接失败）
docker compose logs --tail 100 backend

# 3. 检查 PostgreSQL 是否健康
docker exec wecom_it_postgres pg_isready -U wecom -d wecom_it_desk

# 4. 检查 Redis 是否健康
docker exec wecom_it_redis redis-cli ping

PostgreSQL 密码错误

# ⚠️ 这会清空所有数据！只有首次部署密码错误时才需要
docker compose down
docker volume rm wecom-it-desk_postgres_data
docker compose up -d

H5/坐席端白屏

# 检查前端文件是否存在
docker exec wecom_it_nginx ls /usr/share/nginx/html/itdesk/
docker exec wecom_it_nginx ls /usr/share/nginx/html/itagent/

# 检查 index.html 中的 base 路径是否正确
docker exec wecom_it_nginx cat /usr/share/nginx/html/itdesk/index.html | grep /itdesk/
docker exec wecom_it_nginx cat /usr/share/nginx/html/itagent/index.html | grep /itagent/

DNS 未生效

# 在服务器上验证
nslookup itsupport.servyou.com.cn

# 如果 DNS 未配置，临时用 IP 直接访问
curl http://10.80.0.136/itdesk/
curl http://10.80.0.136/api/health

Mock 登录返回 401

# 1. 确认 .env 中 MOCK_LOGIN_ENABLED=true
cat /opt/wecom-it-desk/.env | grep MOCK

# 2. 检查后端日志
docker compose logs --tail 50 backend | grep mock

# 3. 直接测试 mock-login 接口
curl -X POST http://localhost/api/h5/mock-login \
  -H "Content-Type: application/json" \
  -d '{"employee_id":"test001","employee_name":"测试用户"}'

十、HTTPS 配置（可选）

如果公司要求 HTTPS，有两种方式：

方式一：公司统一 SSL 终端（推荐）

客户端 → HTTPS → 公司SSL终端(F5/网关) → HTTP → 10.80.0.136:80

不需要在本服务器上配置证书。联系运维配置 SSL 终端即可。

方式二：本机 SSL

编辑 nginx/nginx.conf，取消 HTTPS server 块注释，配置证书路径。

十一、与 NAS 部署的差异

维度	NAS 部署（10.80.0.136 旧）	新服务器部署（10.80.0.136 新）
容器数量	5个（含 cloudflared）	4个（无 cloudflared）
外网访问	Cloudflare Tunnel	公司 DNS 直连
域名	itdesk.amanzac.com	itsupport.servyou.com.cn
SSL	Cloudflare 自动	无（内网 HTTP）或公司统一 SSL
数据平台反代	需要（共用域名）	不需要（独立域名）
部署目录	`/volume1/docker/wecom-it-desk`	`/opt/wecom-it-desk`
文件传输	File Station / 7z	SCP 通过堡垒机

12 KiB Raw Permalink Blame History Unescape Escape