diff --git a/docs/ops/mongodb-readonly.md b/docs/ops/mongodb-readonly.md new file mode 100644 index 0000000..0b1438d --- /dev/null +++ b/docs/ops/mongodb-readonly.md @@ -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 开关操作(验证步骤里的写入命令**只允许失败**)。 +- 不打印、不记录、不提交连接串;报告里只写“已创建/已验证”,不写主机、账号、密码。