📝 Document the read-only MongoDB account for Copilot diagnostics

This commit is contained in:
wishforge 2026-11-08 20:34:29 -08:00
parent b11536fcfc
commit 60e911d427

View File

@ -0,0 +1,113 @@
# MongoDB 只读账号(给平台方管理员执行)
Copilot 与运维排查需要读取线上 MongoDB 的**元数据**(集合、计数、连接数、慢操作),但绝不能改动客户数据。
本文给出一次性创建只读账号的步骤、验证方法和凭据存放位置。**本文不含、也不应写入任何真实连接串或密码。**
## 1. 现有部署事实(推断依据)
| 事实 | 依据 |
| --- | --- |
| 平台使用 MongoDB,且数据库在集群外托管,不在 K8s 清单里创建 | `docs/deployment.md:150-158`“主部署路径不再创建平台 MongoDB Pod/Service,必须外部提供 URI” |
| 连接串来自命名空间内的 Secret `droboticflow-mongo-secret`,键名 `MONGO_URI` | `docs/deployment.md:159`、`k8s/droboticflow.template.yaml` 中的 `secretKeyRef` |
| 业务库名来自 ConfigMap `droboticflow-config` 的 `MONGO_DB` | `k8s/droboticflow.template.yaml:132`、`k8s/annotation-processor.template.yaml:33-35` |
| 部署脚本拒绝 `localhost`、`mongodb:27017`、`.svc` 等集群内地址,只接受具体的外部 `mongodb://` / `mongodb+srv://` | `docs/deployment.md:224` |
| 验收探针用短命 `mongo:7` Pod 读取 `MONGO_DB` 做校验,且只读、不打印 URI | `docs/operations.md:300` |
| 平台整体部署在百度云(镜像走百度云 CCR) | `docs/custom-operator-manual.zh-CN.md:176` |
推断结论:这是一个**集群外的托管 MongoDB(部署在百度云,具体产品与主机以现有 Secret 的 host 和百度云控制台为准)**。
核对时只看 `MONGO_DB` 与主机域名,**不要在终端、日志、聊天或提交里打印 `MONGO_URI`**。
同理,**不要用应用自身的 `MONGO_URI` 账号去建用户**(它大概率是读写账号),也不要在这个库上执行任何写入。
下面所有命令都由平台方用管理员账号在 `mongosh` 里手动执行。
## 2. 创建只读账号(管理员执行)
密码用你自己的强随机密码替换占位符,不要写进仓库、聊天或工单。
```js
// 以管理员身份连接(连接串单独从安全位置读取,勿粘贴到共享终端记录里)
// mongosh "<管理员连接串>"
use admin
db.auth("<管理员账号>", "<管理员密码>")
// 业务库名以 ConfigMap 为准:kubectl -n <命名空间> get cm droboticflow-config -o jsonpath='{.data.MONGO_DB}'
use <业务库名>
db.createUser({
user: "wishforge_observer",
pwd: "<强随机密码,占位符>",
roles: [
{ role: "read", db: "<业务库名>" }, // 只读业务库
{ role: "clusterMonitor", db: "admin" } // 连接数、慢操作、副本集状态
]
})
```
说明:
- 只给 `read`,**不要**给 `readWrite`、`dbAdmin`、`dbOwner`、`userAdminAnyDatabase`、`root`。
- `clusterMonitor` 是内置只读角色,可看 `serverStatus`(连接数)、`currentOp`(慢操作)、`replSetGetStatus`,不含集合数据写权限。
- 账号建在业务库上,因此连接时 `authSource` 必须是业务库名,而不是 `admin`。
- 慢查询若要看 `system.profile`,需要 `dbAdmin` 才能开 profiling 并读该集合;默认**不授予**,慢操作排查用 `currentOp` 采样即可。
## 3. 验证账号确实不能写(只读账号执行)
用新账号连一次(`readPreference=primary`,`authSource=<业务库名>`),逐条确认:
```js
use <业务库名>
db.runCommand({ connectionStatus: 1 })
// 期望:authenticatedUsers 只有 wishforge_observer;
// authenticatedUserRoles 只有 <业务库名>.read 与 admin.clusterMonitor
db.getCollectionNames() // 期望:正常返回集合名
db.getCollection("<任一集合>").findOne() // 期望:正常返回一条文档(只读可读)
db.getCollection("<任一集合>").insertOne({ _id: "readonly_probe" })
// 期望:MongoServerError: not authorized on <业务库名> to execute command { insert: ... }
db.getCollection("<任一集合>").updateOne({ _id: "<任一存在的 id>" }, { $set: { readonly_probe: 1 } })
// 期望:not authorized ... update
db.getCollection("<任一集合>").deleteOne({ _id: "<任一存在的 id>" })
// 期望:not authorized ... delete
db.createCollection("readonly_probe")
// 期望:not authorized ... create
// 只读可观测能力(clusterMonitor)
db.runCommand({ serverStatus: 1 }).connections // 期望:返回连接数
db.currentOp({ active: true, secs_running: { $gt: 5 } }) // 期望:返回慢操作列表
db.adminCommand({ replSetGetStatus: 1 }) // 期望:副本集状态(单机部署会报 not supported)
```
四条写入命令(insert / update / delete / create)必须全部报 `not authorized`;任何一条成功,说明角色给多了,立即 `db.updateUser` 收回。
## 4. 凭据存放位置
- 只读连接串存 `local-data/mongodb-readonly.env`(`chmod 600`),字段形如
`MONGO_READONLY_URI=<占位符>`、`MONGO_READONLY_DB=<业务库名>`。
- `local-data/` 不进仓库。本仓库 `.gitignore` 目前**没有** `local-data/` 规则,
需在 `.gitignore` 增补(或至少写进 `.git/info/exclude`),并在提交前用
`git check-ignore -v local-data/mongodb-readonly.env` 确认。
- 不要把它写进 K8s Secret 之外的任何清单;需要给 Copilot 用时,由平台侧注入环境变量。
- 不要把该账号写进 `.scratch/` 笔记、验收日志或聊天记录。
## 5. 吊销与轮换
```js
use <业务库名>
db.dropUser("wishforge_observer") // 吊销
// 或仅轮换密码:
db.updateUser("wishforge_observer", { pwd: "<新密码,占位符>" })
```
轮换后同步更新 `local-data/mongodb-readonly.env`,并确认 Copilot 侧重新读取配置。
## 6. 禁止事项
- 不用应用自身的读写账号建用户或测试权限。
- 不对业务库执行任何写入、建集合、建索引、profiling 开关操作(验证步骤里的写入命令**只允许失败**)。
- 不打印、不记录、不提交连接串;报告里只写“已创建/已验证”,不写主机、账号、密码。