# df-im-gateway 运维手册

> 四端 IM 网关（飞书/企微/钉钉/Web）远程接入 DevFlow AI Chat。
> 部署拓扑：与 u-relay 同机（39.99.243.191），WS Commander 经 u-relay 连桌面端 df-tunnel。

## 一、拓扑与环境

```
飞书/企微/钉钉/Web ──► df-im-gateway(9191, 同机)
                          │ ws://127.0.0.1:9180/ws/commander (Commander 身份)
                          ▼
                      u-relay(9180, nginx 前置 wss://u-relay.1216.top)
                          │ /ws/agent
                          ▼
                      桌面端 DevFlow(df-tunnel Agent)
```

| 项 | 值 |
|---|---|
| 服务器 | 39.99.243.191:22 (root 免密, Ubuntu 22.04) |
| 部署路径 | /opt/df-im-gateway/（二进制 + data/ + 日志） |
| 监听端口 | 9191（本机明文，nginx 前置 im.1216.top → wss） |
| systemd | df-im-gateway.service（Restart=on-failure, 开机自启） |
| token | devflow-relay-default-token（与 u-relay/桌面端三端同源） |
| 数据库 | /opt/df-im-gateway/data/{sessions.db, audit.db}（SQLite WAL） |

## 二、日常运维

```bash
# 状态 / 日志 / 重启
systemctl status df-im-gateway
journalctl -u df-im-gateway -n 50 --no-pager
systemctl restart df-im-gateway

# 端口验证
ss -tlnp | grep 9191

# 审计查询(最近 20 条)
sqlite3 /opt/df-im-gateway/data/audit.db \
  "SELECT datetime(ts/1000,'unixepoch','+8 hours'), direction, action, chat_id, outcome FROM tunnel_audit ORDER BY id DESC LIMIT 20;"

# 会话映射表
sqlite3 /opt/df-im-gateway/data/sessions.db "SELECT * FROM session_map;"
```

⚠️ systemd 托管，勿 kill Main PID、勿 nohup 起野进程；重启一律 `systemctl restart`。

## 三、发布流程

```powershell
# 本机(Windows)一键发布：单测 → musl 交叉编译 → scp → 原子切换 → 9191 验证 → 失败自动回滚
powershell -File E:\wk-lab\devflow\crates\df-im-gateway\scripts\publish-im-gateway.ps1
# 仅构建不部署: 加 -SkipDeploy；仅部署不构建: 加 -SkipBuild
```

首次部署需手动铺底：
```bash
scp crates/df-im-gateway/deploy/df-im-gateway.service root@39.99.243.191:/etc/systemd/system/
ssh root@39.99.243.191 'systemctl daemon-reload && systemctl enable df-im-gateway'
# nginx(可选,Web 端公网访问时): scp deploy/nginx-im.1216.top.conf → /etc/nginx/conf.d/ && nginx -t && systemctl reload nginx
```

## 四、回滚

```bash
cd /opt/df-im-gateway
systemctl stop df-im-gateway
LATEST=$(ls -t df-im-gateway.bak.* | head -1)
cp "$LATEST" df-im-gateway && chmod +x df-im-gateway
systemctl start df-im-gateway
```

## 五、配置变更

| env | 说明 | 改法 |
|---|---|---|
| GATEWAY_RELAY_TOKEN | 与 u-relay 三端同源，**改必须同步桌面端** | 改 unit Environment= → daemon-reload → restart |
| GATEWAY_DEFAULT_CHANNEL | 默认路由 channel | 同上 |
| GATEWAY_WHITELIST | 用户白名单（空=任何人可用，生产必设！） | 同上 |
| FEISHU_APP_ID/SECRET | 飞书长连接 | 同上 |

## 六、已知项

- token 仍为 MVP 单共享值（per-user 是 S2 计划）
- 日志 gateway.log 追加无轮转，可配 logrotate 或定期 truncate
- 四端 E2E 联调依赖各平台凭证到位（飞书/钉钉/企微）