pro/olons_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8d32376de8dcc8953937664b835f4ecc137103a3
olons_server/docs/工作台与Manager内部配置运维说明.md
T

8.6 KiB
Raw Blame History

工作台与 Manager 内部配置运维说明

更新时间：2026-09-17

1. 背景

im_workbench 需要从 im_manager 读取系统配置，例如：

  • im.uid_encryption_key

读取链路如下：

im_workbench
  -> GET https://admin.118im.com/internal/im-config/third-party/im?keys=uid_encryption_key,UID_ENCRYPTION_KEY,uid_key
  -> im_manager 校验 HMAC 签名
  -> 返回系统配置

这个接口是服务间内部接口，不是普通前端接口。调用方必须带 HMAC 请求头：

X-Service-Name: im-workbench
X-Timestamp: <unix seconds>
X-Nonce: <random nonce>
X-Signature: <hmac-sha256 hex>

签名使用的密钥来自 im_manager 测试环境 Secret 中的：

manager-system / im-manager-secrets / IM_CONFIG_API_SECRET

注意：不要把真实密钥写进 Git 文档或代码。

2. 为什么 .env 不生效

测试环境运行在 Kubernetes Pod 中，服务启动时不会自动读取仓库里的 .env 文件。

当前代码和启动方式是：

  • im_workbench 只读取进程环境变量和 IM_WORKBENCH_CONFIG 指向的 JSON 配置文件。
  • im_manager 的 entrypoint 使用 Pod 环境变量做 envsubst 生成 config.yaml。
  • 两个服务都没有 godotenv.Load()、source .env 或 docker compose env_file 逻辑。

所以测试环境真正生效的是：

Kubernetes Secret / Deployment 环境变量

不是仓库中的 .env。

3. 当前 Kubernetes 配置关系

im_workbench

命名空间：

workbench-system

Deployment：

im-workbench

当前 Pod 里只显式注入：

IM_WORKBENCH_CONFIG=/etc/im-workbench/workbench.json

/etc/im-workbench/workbench.json 来自：

workbench-system / im-workbench-secrets / workbench.json

因此 workbench 的运行时配置要改这个 Secret 里的 workbench.json，或在 Deployment 里显式加环境变量。

im_manager

命名空间：

manager-system

Deployment：

im-manager

Secret：

manager-system / im-manager-secrets

其中和内部配置接口相关的 key：

IM_CONFIG_API_SERVICE_NAME
IM_CONFIG_API_SECRET

4. 必须配置什么

4.1 im_manager 需要允许 im_workbench 调配置接口

im_manager 的 IM_CONFIG_API_SERVICE_NAME 需要支持两个调用方：

im-server,im-workbench

原因：

  • im_server 也需要读取 manager 配置。
  • im_workbench 也需要读取 manager 配置。
  • 如果只配置 im-workbench，会影响 im_server。
  • 如果只配置 im-server，im_workbench 用正确 service name 调用会 401。

目标配置：

IM_CONFIG_API_SERVICE_NAME=im-server,im-workbench

IM_CONFIG_API_SECRET 保持现有值，不要改成空，也不要泄露到日志或文档。

4.2 im_workbench 需要配置 manager 连接信息

workbench.json 中需要有：

{
  "manager": {
    "base_url": "https://admin.118im.com",
    "service_name": "im-workbench",
    "secret": "<填 manager-system/im-manager-secrets 中的 IM_CONFIG_API_SECRET>",
    "uid_key_group": "im",
    "uid_key_keys": [
      "uid_encryption_key",
      "UID_ENCRYPTION_KEY",
      "uid_key"
    ],
    "timeout_ms": 3000
  }
}

也可以不用改 JSON，改成 Deployment 环境变量：

IM_WORKBENCH_MANAGER_BASE_URL=https://admin.118im.com
IM_WORKBENCH_MANAGER_SERVICE_NAME=im-workbench
IM_WORKBENCH_MANAGER_SECRET=<填 manager-system/im-manager-secrets 中的 IM_CONFIG_API_SECRET>

建议优先统一放到 workbench.json，因为当前 workbench 已经通过 Secret 挂载 JSON 配置。

5. 推荐操作流程

步骤 1：更新 manager Secret

将：

manager-system / im-manager-secrets / IM_CONFIG_API_SERVICE_NAME

改为：

im-server,im-workbench

IM_CONFIG_API_SECRET 保持现有值。

步骤 2：更新 workbench Secret

从：

manager-system / im-manager-secrets / IM_CONFIG_API_SECRET

取值，写入：

workbench-system / im-workbench-secrets / workbench.json

目标字段：

{
  "manager": {
    "base_url": "https://admin.118im.com",
    "service_name": "im-workbench",
    "secret": "<IM_CONFIG_API_SECRET>"
  }
}

步骤 3：重启服务

更新 Secret 后需要重启 Pod，确保进程重新读取配置。

建议顺序：

1. 重启 im-manager
2. 重启 im-workbench

原因：

  • 先让 manager 支持 im-workbench service name。
  • 再让 workbench 使用 im-workbench service name 去调用 manager。

6. 验证方法

6.1 验证 manager 是否接受 im-workbench

用 IM_CONFIG_API_SECRET 对请求签名，请求：

GET https://admin.118im.com/internal/im-config/third-party/im?keys=uid_encryption_key,UID_ENCRYPTION_KEY,uid_key
X-Service-Name: im-workbench

期望结果：

{
  "code": 0,
  "data": {
    "values": {
      "uid_encryption_key": "..."
    }
  }
}

如果返回 401，重点检查：

  • IM_CONFIG_API_SERVICE_NAME 是否包含 im-workbench
  • 请求里的 X-Service-Name 是否是 im-workbench
  • IM_CONFIG_API_SECRET 是否和 manager 当前 Secret 一致
  • 签名文本是否为：
METHOD
RequestURI
BodySHA256
Timestamp
Nonce

6.2 验证 workbench 是否加载到 manager 配置

进入 workbench Pod 看环境和配置摘要，注意不要打印真实 secret：

kubectl -n workbench-system exec <im-workbench-pod> -- sh -c 'env | grep IM_WORKBENCH_MANAGER'

或查看挂载配置：

kubectl -n workbench-system exec <im-workbench-pod> -- sh -c 'cat /etc/im-workbench/workbench.json'

检查：

manager.base_url = https://admin.118im.com
manager.service_name = im-workbench
manager.secret 非空

6.3 验证业务接口

从 IM 登录获取 token 后，请求 workbench 接口：

GET https://api.118im.com/v1/workbench
Authorization: Bearer <IM token>
X-MeetingIM-APIKey: <api key>
X-IM-Schema: 1
X-Tenant-Code: <tenant code>

期望：

{
  "code": 0
}

再创建会议，确认 user id 编解码和展示名正常：

POST https://api.118im.com/v1/workbench/meetings
Idempotency-Key: <unique id>
Authorization: Bearer <IM token>
X-MeetingIM-APIKey: <api key>
X-IM-Schema: 1
X-Tenant-Code: <tenant code>
Content-Type: application/json

请求体示例：

{
  "title": "运维验证会议",
  "start_at": "2026-09-18T08:00:00Z",
  "end_at": "2026-09-18T09:00:00Z",
  "location": "",
  "recorder_user_id": "usr...",
  "attendee_user_ids": ["usr..."],
  "reminder_minutes": []
}

期望：

{
  "code": 0,
  "data": {
    "state": "scheduled",
    "organizer": {
      "user_id": "usr...",
      "display_name": "..."
    },
    "participant_names": ["..."]
  }
}

7. 常见问题

7.1 为什么不能从 manager 读取 manager secret

因为 IM_CONFIG_API_SECRET 是调用 manager 配置接口的 HMAC 引导凭证。

如果要读取 manager 配置接口，必须先有这个 secret 才能签名。
所以它不能从同一个 manager 配置接口中获取，只能来自部署环境，例如 Kubernetes Secret。

7.2 为什么 service name 不是 im-server

X-Service-Name 表示调用方服务名。

  • im_server 调 manager 时，应使用 im-server
  • im_workbench 调 manager 时，应使用 im-workbench

manager 侧应该允许多个合法调用方：

im-server,im-workbench

7.3 为什么配置了 .env 还是没用

因为 Kubernetes 不会自动读取仓库 .env。

.env 只有在以下情况才会生效：

  • 程序代码主动 godotenv.Load()
  • 启动脚本 source .env
  • docker compose 配了 env_file
  • CI/CD 将 .env 内容写进 Deployment 或 Secret

当前测试环境都不是这些方式。

7.4 只改 workbench 会怎样

如果只把 workbench 改成：

X-Service-Name: im-workbench

但 manager 仍然只允许：

IM_CONFIG_API_SERVICE_NAME=im-server

那么 workbench 调 manager 会返回 401。

所以需要 manager 和 workbench 一起配置。

8. 最终配置清单

manager：

Namespace: manager-system
Secret: im-manager-secrets

IM_CONFIG_API_SERVICE_NAME=im-server,im-workbench
IM_CONFIG_API_SECRET=<保持现有值>

workbench：

Namespace: workbench-system
Secret: im-workbench-secrets
Key: workbench.json

workbench.json：

{
  "manager": {
    "base_url": "https://admin.118im.com",
    "service_name": "im-workbench",
    "secret": "<manager 的 IM_CONFIG_API_SECRET>",
    "uid_key_group": "im",
    "uid_key_keys": [
      "uid_encryption_key",
      "UID_ENCRYPTION_KEY",
      "uid_key"
    ],
    "timeout_ms": 3000
  }
}
Reference in New Issue View Git Blame Copy Permalink