443 lines
8.6 KiB
Markdown
443 lines
8.6 KiB
Markdown
# 工作台与 Manager 内部配置运维说明
|
||
|
||
更新时间：2026-09-17
|
||
|
||
## 1. 背景
|
||
|
||
`im_workbench` 需要从 `im_manager` 读取系统配置，例如：
|
||
|
||
- `im.uid_encryption_key`
|
||
|
||
读取链路如下：
|
||
|
||
```text
|
||
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 请求头：
|
||
|
||
```http
|
||
X-Service-Name: im-workbench
|
||
X-Timestamp: <unix seconds>
|
||
X-Nonce: <random nonce>
|
||
X-Signature: <hmac-sha256 hex>
|
||
```
|
||
|
||
签名使用的密钥来自 `im_manager` 测试环境 Secret 中的：
|
||
|
||
```text
|
||
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` 逻辑。
|
||
|
||
所以测试环境真正生效的是：
|
||
|
||
```text
|
||
Kubernetes Secret / Deployment 环境变量
|
||
```
|
||
|
||
不是仓库中的 `.env`。
|
||
|
||
## 3. 当前 Kubernetes 配置关系
|
||
|
||
### im_workbench
|
||
|
||
命名空间：
|
||
|
||
```text
|
||
workbench-system
|
||
```
|
||
|
||
Deployment：
|
||
|
||
```text
|
||
im-workbench
|
||
```
|
||
|
||
当前 Pod 里只显式注入：
|
||
|
||
```text
|
||
IM_WORKBENCH_CONFIG=/etc/im-workbench/workbench.json
|
||
```
|
||
|
||
`/etc/im-workbench/workbench.json` 来自：
|
||
|
||
```text
|
||
workbench-system / im-workbench-secrets / workbench.json
|
||
```
|
||
|
||
因此 workbench 的运行时配置要改这个 Secret 里的 `workbench.json`，或在 Deployment 里显式加环境变量。
|
||
|
||
### im_manager
|
||
|
||
命名空间：
|
||
|
||
```text
|
||
manager-system
|
||
```
|
||
|
||
Deployment：
|
||
|
||
```text
|
||
im-manager
|
||
```
|
||
|
||
Secret：
|
||
|
||
```text
|
||
manager-system / im-manager-secrets
|
||
```
|
||
|
||
其中和内部配置接口相关的 key：
|
||
|
||
```text
|
||
IM_CONFIG_API_SERVICE_NAME
|
||
IM_CONFIG_API_SECRET
|
||
```
|
||
|
||
## 4. 必须配置什么
|
||
|
||
### 4.1 im_manager 需要允许 im_workbench 调配置接口
|
||
|
||
`im_manager` 的 `IM_CONFIG_API_SERVICE_NAME` 需要支持两个调用方：
|
||
|
||
```text
|
||
im-server,im-workbench
|
||
```
|
||
|
||
原因：
|
||
|
||
- `im_server` 也需要读取 manager 配置。
|
||
- `im_workbench` 也需要读取 manager 配置。
|
||
- 如果只配置 `im-workbench`，会影响 `im_server`。
|
||
- 如果只配置 `im-server`，`im_workbench` 用正确 service name 调用会 401。
|
||
|
||
目标配置：
|
||
|
||
```text
|
||
IM_CONFIG_API_SERVICE_NAME=im-server,im-workbench
|
||
```
|
||
|
||
`IM_CONFIG_API_SECRET` 保持现有值，不要改成空，也不要泄露到日志或文档。
|
||
|
||
### 4.2 im_workbench 需要配置 manager 连接信息
|
||
|
||
`workbench.json` 中需要有：
|
||
|
||
```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 环境变量：
|
||
|
||
```text
|
||
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
|
||
|
||
将：
|
||
|
||
```text
|
||
manager-system / im-manager-secrets / IM_CONFIG_API_SERVICE_NAME
|
||
```
|
||
|
||
改为：
|
||
|
||
```text
|
||
im-server,im-workbench
|
||
```
|
||
|
||
`IM_CONFIG_API_SECRET` 保持现有值。
|
||
|
||
### 步骤 2：更新 workbench Secret
|
||
|
||
从：
|
||
|
||
```text
|
||
manager-system / im-manager-secrets / IM_CONFIG_API_SECRET
|
||
```
|
||
|
||
取值，写入：
|
||
|
||
```text
|
||
workbench-system / im-workbench-secrets / workbench.json
|
||
```
|
||
|
||
目标字段：
|
||
|
||
```json
|
||
{
|
||
"manager": {
|
||
"base_url": "https://admin.118im.com",
|
||
"service_name": "im-workbench",
|
||
"secret": "<IM_CONFIG_API_SECRET>"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 步骤 3：重启服务
|
||
|
||
更新 Secret 后需要重启 Pod，确保进程重新读取配置。
|
||
|
||
建议顺序：
|
||
|
||
```text
|
||
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` 对请求签名，请求：
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
期望结果：
|
||
|
||
```json
|
||
{
|
||
"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 一致
|
||
- 签名文本是否为：
|
||
|
||
```text
|
||
METHOD
|
||
RequestURI
|
||
BodySHA256
|
||
Timestamp
|
||
Nonce
|
||
```
|
||
|
||
### 6.2 验证 workbench 是否加载到 manager 配置
|
||
|
||
进入 workbench Pod 看环境和配置摘要，注意不要打印真实 secret：
|
||
|
||
```bash
|
||
kubectl -n workbench-system exec <im-workbench-pod> -- sh -c 'env | grep IM_WORKBENCH_MANAGER'
|
||
```
|
||
|
||
或查看挂载配置：
|
||
|
||
```bash
|
||
kubectl -n workbench-system exec <im-workbench-pod> -- sh -c 'cat /etc/im-workbench/workbench.json'
|
||
```
|
||
|
||
检查：
|
||
|
||
```text
|
||
manager.base_url = https://admin.118im.com
|
||
manager.service_name = im-workbench
|
||
manager.secret 非空
|
||
```
|
||
|
||
### 6.3 验证业务接口
|
||
|
||
从 IM 登录获取 token 后，请求 workbench 接口：
|
||
|
||
```http
|
||
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>
|
||
```
|
||
|
||
期望：
|
||
|
||
```json
|
||
{
|
||
"code": 0
|
||
}
|
||
```
|
||
|
||
再创建会议，确认 user id 编解码和展示名正常：
|
||
|
||
```http
|
||
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
|
||
```
|
||
|
||
请求体示例：
|
||
|
||
```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": []
|
||
}
|
||
```
|
||
|
||
期望：
|
||
|
||
```json
|
||
{
|
||
"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 侧应该允许多个合法调用方：
|
||
|
||
```text
|
||
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 改成：
|
||
|
||
```text
|
||
X-Service-Name: im-workbench
|
||
```
|
||
|
||
但 manager 仍然只允许：
|
||
|
||
```text
|
||
IM_CONFIG_API_SERVICE_NAME=im-server
|
||
```
|
||
|
||
那么 workbench 调 manager 会返回 401。
|
||
|
||
所以需要 manager 和 workbench 一起配置。
|
||
|
||
## 8. 最终配置清单
|
||
|
||
manager：
|
||
|
||
```text
|
||
Namespace: manager-system
|
||
Secret: im-manager-secrets
|
||
|
||
IM_CONFIG_API_SERVICE_NAME=im-server,im-workbench
|
||
IM_CONFIG_API_SECRET=<保持现有值>
|
||
```
|
||
|
||
workbench：
|
||
|
||
```text
|
||
Namespace: workbench-system
|
||
Secret: im-workbench-secrets
|
||
Key: workbench.json
|
||
```
|
||
|
||
`workbench.json`：
|
||
|
||
```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
|
||
}
|
||
}
|
||
```
|
||
|