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

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

日期: 2026-07-11
版本: v1.0
代码状态: 40/40 测试通过，待部署
预估部署时间: 30-45 分钟

---

一、部署前置条件

1.1 企微配置

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

1.2 服务器环境

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

1.3 终端设备

• 确认小鱼易联终端型号（当前按浏览器方案设计）
• 终端浏览器支持 WebSocket + ES6

---

二、部署步骤

Step 1: 数据库迁移

# 进入后端容器
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('meetingroom_booking_snapshots' in tables)  # 应为 True
print('terminal_room_bindings' in tables)          # 应为 True
"

Step 2: 环境变量配置

在 docker-compose.yml 中添加：

backend:
  environment:
    - WECOM_MEETINGROOM_SECRET=<your_secret>
    - MEETINGROOM_CACHE_TTL_ROOMS=600
    - MEETINGROOM_CACHE_TTL_BOOKING=30
    - MEETINGROOM_CACHE_TTL_STATUS=10

重启后端：

docker compose up -d backend

Step 3: 后端验证

# 验证 API 端点注册
curl -sk https://localhost/api/itportal/meetingroom/rooms \
  -H "Authorization: Bearer $TOKEN"

# 验证 WS 端点
wscat -c "wss://localhost/ws/terminal/TEST-SN-001"

# 验证管理端绑定 API
curl -sk https://localhost/api/itportal/admin/terminal-bindings \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Step 4: 终端前端部署

# 1. 本地构建
cd frontend-terminal
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/
tar -xzf /tmp/terminal-dist.tar.gz

# 5. Nginx 配置
# 在 nginx.conf 中添加：
location /itterminal/ {
    alias /usr/share/nginx/html/terminal/;
    try_files $uri $uri/ /itterminal/index.html;
}

Step 5: Nginx 重启

docker compose restart nginx

Step 6: H5 端入口验证

H5 端已内置会议室入口（MeetingroomView.vue），无需额外部署。 验证：

curl -sk https://localhost/ith5/ | grep -o 'meetingroom'

---

三、部署后验证

3.1 功能验证清单

#	验证项	验证方法	预期结果
1	会议室列表	GET /api/itportal/meetingroom/rooms	返回会议室列表
2	会议室状态	GET /api/itportal/meetingroom/rooms/{id}/status	返回当前状态
3	预定会议室	POST /api/itportal/meetingroom/bookings	创建预定成功
4	时间线	GET /api/itportal/meetingroom/rooms/{id}/timeline	返回当日时间线
5	终端绑定	POST /api/itportal/admin/terminal-bindings	绑定终端-会议室
6	终端WS	WS /ws/terminal/{sn}	终端状态实时推送
7	终端前端	浏览器打开 /itterminal/	深色主题大屏页面
8	H5入口	H5 端点击会议室入口	跳转 MeetingroomView
9	扫码登录	终端扫码	企微扫码登录成功
10	状态同步	终端修改状态 → H5 实时更新	WS 推送正常

3.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:booking:{room_id}:{date}"

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

---

四、回滚方案

4.1 数据库回滚

# 回退迁移 050
docker compose exec backend alembic downgrade -1

4.2 后端回滚

# 恢复 .py 文件（bind mount 自动生效）
git checkout HEAD~1 -- backend/app/api/meetingroom.py
git checkout HEAD~1 -- backend/app/services/meetingroom_service.py
# ... 其他文件
docker compose restart backend

4.3 前端回滚

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

4.4 Nginx 配置回滚

# 移除 /itterminal/ location 块
docker compose restart nginx

---

五、已知限制

1. 企微API时间限制: 会议室预定查询范围限制 31 天
2. 终端身份: 当前按访客可查看设计，管理操作需扫码登录
3. WS重连: 终端断线后自动重连（指数退避），超过 5 次降级为轮询（10s间隔）
4. 缓存TTL: 会议室列表 600s / 预定 30s / 状态 10s，手动刷新可跳过缓存

---

六、配置参数速查

参数	默认值	环境变量
会议室Token TTL	6900s	-
会议室列表缓存	600s	MEETINGROOM_CACHE_TTL_ROOMS
预定缓存	30s	MEETINGROOM_CACHE_TTL_BOOKING
状态缓存	10s	MEETINGROOM_CACHE_TTL_STATUS
WS重连次数	5	-
WS降级轮询间隔	10s	-