wishforge-ide/docs/ops/mongodb-readonly.md

114 lines
5.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 开关操作(验证步骤里的写入命令**只允许失败**)。
- 不打印、不记录、不提交连接串;报告里只写“已创建/已验证”,不写主机、账号、密码。