wecom_it_smart_desk/docs/09-部署运维/会议室预定-部署指南.md

会议室预定-小鱼易联终端 部署指南

日期: 2026-07-11
版本: v2.0（新增报修+指南+二维码+移动端适配）
代码状态: 待部署
预估部署时间: 45-60 分钟

---

一、部署前置条件

1.1 企微配置

• 企微会议室 Secret 已申请
• 企微会议室已在管理后台创建
• 确认会议室 meetingroom_id 列表

1.2 服务器环境

• PostgreSQL 可用（需执行 Alembic 迁移 050 + 051）
• Redis 可用（会议室缓存依赖）
• Nginx 可用（终端前端静态文件 + API 代理）
• Docker Compose 可用

1.3 终端设备

• 确认小鱼易联终端型号（NE90/NE60 支持 H5 应用，NE2005 需二维码降级）
• 终端浏览器支持 WebSocket + ES6
• 小鱼管理后台可访问（配置 H5 应用入口）

---

二、部署步骤

Step 1: 数据库迁移

# 进入后端容器执行迁移（050 会议室基础表 + 051 报修+指南表）
docker compose exec backend alembic upgrade head

# 验证新表
docker compose exec backend python -c "
from app.database import engine
from sqlalchemy import inspect
insp = inspect(engine)
tables = insp.get_table_names()
print('terminal_room_bindings' in tables)   # 应为 True（050）
print('meetingroom_guide' in tables)         # 应为 True（051）
print('meetingroom_repair' in tables)        # 应为 True（051）
"

Step 2: 环境变量配置

在 .env 中添加：

# 终端页面基础URL（用于NE2005二维码生成）
TERMINAL_BASE_URL=https://itsupport.servyou.com.cn/itterminal/

在 docker-compose.yml 的 backend environment 中已添加：

- TERMINAL_BASE_URL=${TERMINAL_BASE_URL:-https://itsupport.servyou.com.cn/itterminal/}

重启后端：

docker compose up -d backend

Step 3: 后端验证

# 验证会议室 API（已存在）
curl -sk https://localhost/itportal/meetingroom/list

# 验证报修 API（新增）
curl -sk -X POST https://localhost/itportal/meetingroom/repair \
  -H "Content-Type: application/json" \
  -d '{"terminal_sn":"TEST-SN","meetingroom_id":1,"meetingroom_name":"测试","device_type":"projector","fault_description":"测试报修"}'

# 验证指南 API（新增）
curl -sk https://localhost/itportal/meetingroom/guides

# 验证二维码 API（新增）
curl -sk https://localhost/itportal/meetingroom/terminal/TEST-SN/qrcode -o /tmp/qr.png
file /tmp/qr.png  # 应为 PNG image

Step 4: 终端前端构建与部署

# 1. 本地构建
cd frontend-terminal
npm install  # 安装新增的 qrcode 依赖
npm run build

# 2. 打包
tar -czf terminal-dist.tar.gz dist/

# 3. 上传到服务器（通过堡垒机）
python C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py \
  pack-upload ./terminal-dist.tar.gz /opt/wecom-it-desk/frontend-terminal/

# 4. 服务器解压
cd /opt/wecom-it-desk/frontend-terminal/
rm -rf dist  # 删除旧 dist（bind mount 铁律：rm后重建必须重启容器）
tar -xzf /tmp/terminal-dist.tar.gz

Step 5: Nginx 配置更新

nginx/nginx.conf 已更新，新增以下 location（两个 server 块均已添加）：

# 小鱼终端大屏 — /itterminal/
location /itterminal/ {
    alias /usr/share/nginx/html/itterminal/;
    index index.html;
    try_files $uri /itterminal/index.html;
}

# 会议室 API — /itportal/meetingroom/
# 必须在 /itportal/ 静态文件之前匹配（nginx 最长前缀优先）
location /itportal/meetingroom/ {
    proxy_pass http://backend_api;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 60s;
    proxy_send_timeout    300s;
    proxy_read_timeout    300s;
}

docker-compose.yml nginx volumes 已添加：

- ./frontend-terminal/dist:/usr/share/nginx/html/itterminal:ro

重启 Nginx：

docker compose restart nginx

Step 6: 终端前端验证

# 验证终端页面可访问
curl -sk https://localhost/itterminal/ | head -5

# 验证 API 代理（通过 nginx 访问后端）
curl -sk https://localhost/itportal/meetingroom/guides

# 验证静态资源
curl -sk -o /dev/null -w "%{http_code}" https://localhost/itterminal/assets/index-*.js

---

三、小鱼管理后台 H5 应用配置

3.1 支持型号确认

型号	H5 应用支持	配置方式
NE90	✅ 支持	小鱼管理后台配置 H5 应用入口
NE60	✅ 支持	同上
NE20	✅ 支持	同上
AE2060	✅ 支持	同上
ME55S	⚠️ 部分固件支持	需确认固件版本
NE2005	❌ 不支持	使用二维码降级方案

3.2 H5 应用入口配置（NE90/NE60/NE20/AE2060）

1. 登录小鱼易联管理后台（https://mt.xylink.com）
2. 进入 应用管理 > 自定义应用
3. 创建新应用：
   • 应用名称: IT智能服务台
   • 应用类型: H5 网页应用
   • 访问地址: https://itsupport.servyou.com.cn/itterminal/{终端SN}/
   • 展示方式: 终端主界面快捷入口
4. 推送应用到目标终端
5. 在终端上验证 H5 应用可正常打开

3.3 终端 SN 绑定

在管理后台（/itadmin/）的终端绑定页面中：

1. 添加终端 SN 与会议室的绑定关系
2. 每个终端 SN 对应一个企微会议室 ID
3. 绑定后终端页面自动加载对应会议室状态

3.4 NE2005 二维码降级方案

对于不支持 H5 应用的 NE2005 终端：

1. 生成二维码：

   # 通过 API 生成终端访问二维码
   curl -sk https://itsupport.servyou.com.cn/itportal/meetingroom/terminal/{SN}/qrcode -o qr.png
   

   或直接在浏览器访问： https://itsupport.servyou.com.cn/itportal/meetingroom/terminal/{SN}/qrcode

2. 打印二维码：将二维码打印为贴纸（建议尺寸 10×10cm）

3. 张贴二维码：贴在 NE2005 终端的显眼位置

4. 用户使用流程：

   • 用户用企业微信/微信扫描二维码
   • 手机浏览器打开终端页面（移动端自适应布局）
   • 可查看会议室状态、预定、报修、查看指南

---

四、部署后验证

4.1 功能验证清单

#	验证项	验证方法	预期结果
1	会议室列表	GET /itportal/meetingroom/list	返回会议室列表
2	会议室状态	GET /itportal/meetingroom/{id}/status	返回当前状态
3	预定会议室	POST /itportal/meetingroom/book	创建预定成功
4	终端绑定	GET /itportal/meetingroom/terminal/{sn}/binding	返回绑定信息
5	终端WS	WS /ws/terminal/{sn}	终端状态实时推送
6	设备报修	POST /itportal/meetingroom/repair	创建工单+通知管理员
7	指南列表	GET /itportal/meetingroom/guides	返回指南列表(5条种子)
8	指南按类型	GET /itportal/meetingroom/guides/projector	返回投影仪指南
9	终端二维码	GET /itportal/meetingroom/terminal/{sn}/qrcode	返回PNG图片
10	终端前端	浏览器打开 /itterminal/{sn}/	深色主题大屏页面
11	报修页面	终端点击"设备报修"按钮	显示报修表单
12	指南页面	终端点击"操作指南"按钮	显示指南列表+二维码
13	移动端适配	手机访问 /itterminal/{sn}/	垂直布局自适应
14	扫码登录	终端扫码	企微扫码登录成功
15	状态同步	终端修改状态 → H5 实时更新	WS 推送正常

4.2 Redis 缓存验证

# 会议室 token
redis-cli -a $REDIS_PASSWORD get wecom:meetingroom_access_token

# 会议室列表缓存
redis-cli -a $REDIS_PASSWORD get meetingroom:room_list

# 状态缓存
redis-cli -a $REDIS_PASSWORD get "meetingroom:status:{room_id}"

---

五、回滚方案

5.1 数据库回滚

# 回退迁移 051（报修+指南表）
docker compose exec backend alembic downgrade -1

# 完全回退（含 050）
docker compose exec backend alembic downgrade -2

5.2 后端回滚

# 恢复 .py 文件（bind mount 自动生效）
git checkout HEAD~1 -- backend/app/api/meetingroom.py
git checkout HEAD~1 -- backend/app/services/repair_service.py
git checkout HEAD~1 -- backend/app/services/meetingroom_service.py
git checkout HEAD~1 -- backend/app/models/meetingroom_guide.py
git checkout HEAD~1 -- backend/app/models/meetingroom_repair.py
git checkout HEAD~1 -- backend/app/schemas/meetingroom.py
git checkout HEAD~1 -- backend/app/config.py
docker compose restart backend

5.3 前端回滚

# 恢复旧 dist
mv /opt/wecom-it-desk/frontend-terminal/dist /opt/wecom-it-desk/frontend-terminal/dist.bak
# 恢复上一版本
docker compose restart nginx

5.4 Nginx 配置回滚

# 移除 /itterminal/ 和 /itportal/meetingroom/ location 块
docker compose restart nginx

---

六、新增功能说明

6.1 设备报修流程

终端用户点击"设备报修"
  → 选择设备类型（投影仪/视频会议/空调/桌椅/网络/其他）
  → 填写故障描述
  → 提交报修
  → 后端创建:
    1. MeetingroomRepair 记录
    2. Conversation（IT工单会话，状态=排队，紧急度=3）
    3. Message（系统消息，含故障描述）
    4. 企微消息通知管理员
    5. WS广播给在线坐席
  → 终端显示"报修已提交"
  → 3秒后自动返回状态页

6.2 操作指南双模式

• 终端展示：指南的 brief 字段在终端大屏上直接显示简要操作步骤
• 二维码详情：指南的 detail_url 生成二维码，用户手机扫码查看完整文档
• 管理员可在数据库中添加/修改指南内容

6.3 NE2005 降级流程

NE2005 终端（不支持H5应用）
  → 管理员生成二维码贴纸（API: /itportal/meetingroom/terminal/{sn}/qrcode）
  → 用户手机扫码
  → 手机浏览器打开终端页面（移动端自适应）
  → 功能与终端大屏一致（状态/预定/报修/指南）

---

七、配置参数速查

参数	默认值	环境变量
会议室Token TTL	6900s	-
会议室列表缓存	600s	MEETINGROOM_CACHE_TTL_ROOMS
预定缓存	30s	MEETINGROOM_CACHE_TTL_BOOKING
状态缓存	10s	MEETINGROOM_CACHE_TTL_STATUS
WS重连次数	5	-
WS降级轮询间隔	10s	-
终端页面URL	https://itsupport.servyou.com.cn/itterminal/	TERMINAL_BASE_URL
二维码尺寸	300px	API 参数 size
二维码缓存	1小时	HTTP Cache-Control

---

八、已知限制

1. 企微API时间限制: 会议室预定查询范围限制 31 天
2. 终端身份: 管理操作需扫码登录，报修支持匿名提交
3. WS重连: 终端断线后自动重连（指数退避），超过 5 次降级为轮询（10s间隔）
4. NE2005: 不支持 H5 应用，仅能通过二维码扫码方式使用
5. 指南管理: 当前通过数据库直接管理，后续可增加管理后台 UI