管理员手册

OCTO 文档中心 · 用户手册

知识库产品/架构/部署active文档推导
04-user-manual/普通用户快速上手指南.md风格参考

OCTO 管理员手册 v1.0

面向读者：OCTO 私有化部署后的系统管理员/运维角色——负责账号、Space、Bot、插件市场、系统配置、监控与安全日常管理的人员。

版本基线：octo-server v1.18.0（开源）/ Web 2026.09.14 / iOS 1.0.5 / Android 1.4.0 / openclaw-channel-octo 插件 1.5.0。生产版本以交付部署包 pin 的 tag 为准。

⚠️ UI 免责声明：本手册的管理操作基于产品能力文档与 octo-server 源码已确认的后端能力整理；管理后台（`/admin/`）的页面布局、菜单名称、按钮位置以实际部署的产品界面为准。后端能力标注【✅源码确认】处均有 octo-server 源码依据；未标注处为能力推导，待走查验证。

术语约定：全篇使用 Space（团队空间） 一词。OCTO 源码中无 organization 概念，Space = organization = workspace（来源：02-architecture/权限模型与鉴权体系.md 硬口径①）。

[管理员角色与权限边界](#一管理员角色与权限边界)
[Space（团队空间）管理](#二spaceteam空间管理)
[用户管理](#三用户管理)
[Bot 管理](#四bot管理)
[插件市场管理](#五插件市场管理)
[系统设置](#六系统设置)
[运行时监控与日志](#七运行时监控与日志)
[安全管理](#八安全管理)
[常见管理问题 FAQ](#九常见管理问题-faq)
[附录：管理员速查表 + 相关文档索引](#十附录管理员速查表--相关文档索引)

一、管理员角色与权限边界

1.1 你是哪种管理员

角色体系	取值	说明
① Space 成员角色（租户内身份）	普通成员(0) / 管理员(1) / 拥有者(2)	决定你在某个 Space 内的管理权限：成员管理、Space 设置、转让/解散
② 群成员角色（群内身份）	普通群成员(0) / 群主(1) / 管理者(2)	决定你在某个群内的管理权限：群设置、加人踢人、公告。另有独立 `bot_admin` 布尔标志位
③ 系统平台角色（全局身份）	`admin` / `superAdmin` / `dashboardReader` / `marketAdmin`	挂在 `user.role` 上，在 Space 角色之上，决定能否进入管理后台 `/admin/` 及平台级操作

平台角色	权限范围
superAdmin（超级管理员）	最高系统权限，管理其他管理员账号
admin（平台管理员）	平台级管理：用户/Space/Bot/系统设置等管理后台操作
dashboardReader（看板只读）	受限角色，仅能读数据看板
marketAdmin（市场发布）	受限角色，仅能发布到技能/插件市场

1.2 首位管理员从哪来

OCTO 默认关闭公开自助注册（register.off: true）。
首位 superAdmin 在部署时 out-of-band 创建：设置 OCTO_ADMIN_PWD 环境变量自动 bootstrap，或手动 SQL seed（来源：03-deployment-ops/部署FAQ-v0.1.md Q7）。
后续管理员由 superAdmin 在管理后台创建；普通用户由管理员创建/邀请，或配置 SSO（OIDC）登录。

1.3 🔴 权限红线（必须牢记，管理操作不能越界）

🔴 红线①：无 organization 概念，租户边界唯一是 Space

源码中不存在 "organization" 一级租户实体（全仓 `org_id` 搜索 0 命中）。不存在"组织下多 Space"的层级，Space 就是最顶层租户单元。管理后台中的"成员管理"对应的是 Space 成员管理。

🔴 红线②：不支持自定义 RBAC（角色硬编码枚举）

三套角色均为代码硬编码，没有管理员自定义角色、权限点粒度拆分、可视化权限矩阵、按岗位授权能力。`marketAdmin` 角色源码注释明确写着 `"before general manager RBAC exists"`——通用 RBAC 尚不存在，是规划项。用户提出"自定义角色/精细授权"需求时，如实告知当前版本不支持。

🔴 红线③：多租户是同库逻辑隔离（space_id 过滤），非物理隔离

所有 Space 的数据存于同一个数据库实例、同一套表、同一套 OpenSearch 索引，靠 `space_id` 字段在查询层强制过滤实现隔离。隔离由多层 guard 保障（SpaceMiddleware / OpenSearch 强制 term filter / 防枚举 NOT_FOUND），不是独立数据库/独立 Schema/物理隔离部署。

🔴 R5：管理端点复用 `/v1/*`，无独立 admin API 前缀，也无公开 OpenAPI/Swagger 规范文档。管理操作走管理后台 UI；程序化对接首选 Bot API（`/v1/bot/*`）。不要向集成方承诺"有独立管理 API 可调用"。

1.4 权限生效机制（管理员需要知道的延迟）

鉴权执行为 middleware + handler 双层检查；Space 成员资格与用户系统角色有 Redis 缓存，TTL 60s（正向命中 60s / 否定命中 30s / 系统角色 60s）（来源：权限模型与鉴权体系.md §2.4）。
含义：移除某人的管理员权限后，最坏情况下 60s 内其仍可能执行管理操作。高安全场景下做权限回收后应留意该窗口。
部分系统设置（如文件扩展名黑白名单）跨实例最长 60s 收敛【✅源码确认：system_setting schema 注释】。

1.5 管理后台登录与 MFA

管理后台地址：https://<你的OCTO地址>/admin/（nginx /admin/ 路由托管 octo-admin 静态资源；来源：部署FAQ Q1）。
管理端登录支持邮箱二次验证（MFA）：系统设置 login.manager_email_mfa_on 开启（默认关闭），开启后仅保护管理控制台登录端点【✅源码确认：system_setting schema + modules/user/api_manager.go MFA 端点】。生产环境建议开启，需同时配置 support.email 系列 SMTP 设置（见 §6.4）。

二、Space（团队空间）管理

2.1 Space 是什么

Space = 租户隔离的唯一单元 = organization = workspace。成员管理、权限隔离、跨部门边界的锚点都是 Space。一个用户可同时属于多个 Space（User⇄Space 多对多），每个 Space 内身份/角色独立。（来源：权限模型与鉴权体系.md §1.1-1.3）

2.2 日常管理操作

操作	说明
查看 Space 列表	活跃空间列表；另有已解散/已封禁空间列表
代建 Space	管理端代建空间（为部门/项目组建新租户单元）
查看 Space 详情	成员数、配置等
修改 Space 资料	名称、加入方式、成员上限等基础信息
成员管理	成员列表 / 强制添加 / 强制移除成员
修改成员角色	调整某成员为 owner/admin/member（Space 三档角色）
封禁/解禁 Space	状态 2=封禁 / 1=解禁
强制解散 Space	谨慎操作，解散后不可恢复（以实际界面提示为准）
邀请链接管理	创建/修改邀请（max_uses 次数上限 / expires_at 过期时间 / status 状态）/ 软禁用邀请码
入群申请审批	查看并 approve/reject Space 加入申请
Space 拥有者邮箱邀请	创建/列表/撤销 owner 邮箱邀请

2.3 Space 相关系统设置

space.disable_user_create：是否关闭普通用户自助创建 Space 的入口（来源：system_setting schema【✅源码确认】）。企业管控行为：建议开启关闭，统一由管理员建 Space。
space.oidc_initial_space_id：OIDC SSO 建号后自动加入的初始 Space（须为已存在且未解散的 space_id；留空=关闭）。

2.4 管理建议

一个租户边界一个 Space：内部部门协作、外部客户协作分开建 Space；外部协作优先用外部群打标机制而非混编成员。
成员上限在 Space 资料中配置（updateSpaceProfile）；规划容量时注意所有 Space 共享同一套数据库与存储资源（同库逻辑隔离，见红线③）。
强合规客户（金融/政企/涉密）：必须采用"一客户一部署实例"方案（独立数据库+独立服务+独立 OpenSearch），不要在同一实例内承诺"强物理隔离"（来源：权限模型与鉴权体系.md §4.1）。

三、用户管理

3.1 账号从哪来（三种途径）

管理员后台创建【✅源码确认：`POST /user/add`，支持姓名/手机号/区号/密码】；
邀请加入 Space（邀请链接 / Space owner 邮箱邀请，见 §2.2）；
SSO 自动建号：配置 OIDC 后由 `AllowNewUser` 开关控制是否自动创建新用户，支持 `AutoLinkByEmail` / `AutoLinkByPhone` 按邮箱/手机号自动关联既有账号（来源：权限模型与鉴权体系.md §5.1）。

3.2 日常用户管理操作

操作	说明
用户列表 / 搜索	分页查询用户
添加用户	姓名 + 手机号 + 密码（区号）
重置用户密码	用户忘记密码时的官方重置路径（OCTO 无公开自助找回流程）
封禁 / 解禁用户	`liftban`；封禁用户进入封禁列表（disablelist）
封禁用户列表	查看已封禁账号
查看用户好友 / 黑名单	排查关系链问题
在线设备信息 / 设备列表	查看某用户登录设备，排查异常登录
修改用户密码	管理员直接改密（与"重置"入口区分以实际界面为准）
批量用户信息查询	一次最多 200 个 uid（见 3.4）

3.3 短号（short_no）说明

若部署配置 ShortNo.NumOn 开启：调用短号服务生成数字短号；否则用时间戳 hex 兜底生成。
短号有唯一性约束；ShortNo.EditOff 配置决定用户是否可自行编辑短号（关闭编辑时 shortNumStatus=1）。
用户资料接口会下发 short_no 字段。
⚠️ 管理后台是否提供"手动改短号"的 UI 入口待确认——当前确认级事实是"创建时自动生成 + 配置控制可否编辑"，不要承诺管理员可任意改号（具体以实际界面为准）。

3.4 批量操作边界

批量用户信息解析 ≤200 个 uid【✅源码确认：MaxBatchUserUIDs = 200（modules/user/batch.go），请求体上限 32KB，超限/重复/超长统一返回 400】。Bot API 侧的批量接口 /v1/bot/users/batch 同样受 members≤200 / message_ids≤100 限制（来源：04-api-integration/Bot-API错误码与排障-v1.0.md §5.1）。
没有"批量建号/批量导入通讯录"的已确认管理功能——SCIM 自动 provisioning/deprovisioning 明确不支持（无实现，来源：权限模型与鉴权体系.md §5.2）。大批量开户建议脚本调管理端点或走 SSO 建号，具体以交付方案为准。

3.5 账号生命周期注意

封禁用户立即失去访问；但注意权限缓存最长 60s 收敛（§1.4）。
账号注销（destroy）为独立流程，含冷静期状态（is_destroy applying/done），批量接口对非存活账号返回 missing_uids【✅源码确认：modules/user/api_batch.go】。
SSO 侧 sync_worker 只做 token 轮转/失败吊销踢线/实名 claims 同步，不做账号生命周期管理（来源：权限模型与鉴权体系.md §5.2）——SSO 侧离职停用后 OCTO 侧账号仍需管理员处理。

四、Bot 管理

4.1 两类 Bot，两套管理入口

🔑 市场 ≠ BotFather：Bot 的创建/管理唯一入口是私聊 BotFather，不经插件市场分发（来源：01-product/模块说明/市场Marketplace模块.md §1.2）。

维度	User Bot（用户机器人）	App Bot（应用机器人）
Token 前缀	`bf_`	`app_`
创建入口	私聊 BotFather（IM 命令）	App 管理后台 / 管理端 API【✅源码确认：`/v1/admin/app_bot` 与 `/v1/space/:space_id/app_bot`】
典型用途	群内助手、技能专家、工作流 Bot	企业自建应用、OBO 调用、第三方集成
群端点访问	✅ 受群成员资格门控	🔴 完全拒绝群端点，仅限 DM（私聊）
Scope 粒度	按群成员资格控制	仅 `platform`（全平台）/`space`（单 Space）两档粗粒度，无 OAuth2 细粒度 scope 体系
Space 座位	❌ 不占（无 space_member 行）	❌ 不占

4.2 User Bot：BotFather 创建流程

命令	作用
`/newbot`	创建新 Bot（进入向导：填名字→生成 token）
`/mybots`	我创建的 Bot 列表
`/token`	查看/管理 token
`/revoke`	重置（吊销）token
`/connect` / `/disconnect`	连接/断开 runtime
`/setname` / `/setdescription`	改名/改简介
`/deletebot`	删除 Bot（有确认步骤）
`/approve` / `/reject` / `/pending`	审批相关（Bot 申请等）
`/daemon`	获取本地运行时（octo-daemon）安装命令 + server URL + space-scoped API key（回路/Fleet 用）
`/help` / `/start` / `/cancel` / `/quickstart` / `/install`	帮助/开始/取消向导等

4.3 User Bot：管理后台侧操作

操作	说明
机器人列表（分页）/ 详情 / 编辑	查看、修改 Bot 资料
修改机器人状态	启用/禁用 Bot（`PUT /robot/status/:robot_id/:status`）
删除机器人	删除 Bot 身份
重置 Token	`POST /robots/:robot_id/revoke_token`，立即吊销旧 token
机器人菜单管理	查看/删除 Bot 命令菜单

🔴 Token 永不过期，仅手动重置：robot 表 bot_token 字段无 expires 列，鉴权只查 `bot_token=? and status=1`——token 永不自动过期，仅"手动重置 / Bot 删除 / Bot 禁用"三种情况失效【✅源码确认，来源：04-api-integration/Bot-API快速入门-v1.0.md A-6 补证】。

管理含义：token 泄露不会自愈，必须管理员主动 revoke；轮换周期由企业安全策略自定。吊销经共享墓碑缓存即时生效（App Bot 侧另有鉴权缓存兜底 TTL，默认 60s，见 §6.3）。

4.4 App Bot：创建/发布/Token 管理

🔴 App Bot 未发布 = 不可用（403）：草稿状态的 App Bot 调用 Bot API 返回 403 `bot_unavailable`。必须在管理后台/插件市场发布后才能使用【✅源码确认，来源：04-api-integration/Bot-API错误码与排障-v1.0.md §4.2】。新建 App Bot 后记得发布，这是"新 Bot 调不通"的最常见原因之一。

🔴 App Bot 只能私聊（DM-only）：App Bot 调用群相关 API 直接被 authtree 路由守卫拒绝（403 `app_bot_dm_only`）。售前/集成侧不要承诺"App Bot 群聊能力"（来源：权限模型与鉴权体系.md §3.2）。

4.5 Bot 权限边界（向用户解释时的固定口径）

🔴 Bot 是普通群成员，不是超管：只能操作自己加入的群；拉群列表只返回自己在的群；被踢出后立即失去该群访问权（来源：售前红线卡 G8/R3）。
🔴 解散群/修改成员角色不对 Bot 开放：这类管理操作走后台 UI，无对应 Bot API（来源：售前红线卡 R4）。
Bot 不占 Space 座位、不占"人头数"（无 space_member 行）。
Bot 需先被拉进群才能在群里被 @ 并回复；User Bot 在群里默认与普通成员同权。
新成员（含 Bot）能否看入群前历史消息由群级开关 allow_view_history_msg 控制（UI 暴露入口待确认，AUTH-02）。

五、插件市场管理

市场定位：Marketplace = Skills 与 MCP servers 的目录+发布服务（独立微服务 octo-marketplace），分发 4 种插件类型：expert（专家）/ expert_team（专家团）/ skill（技能包）/ connector（连接器，即 MCP server）。上限常量：专家团成员 ≤30、单专家技能 ≤20。Bot 不是分发类型。（来源：01-product/模块说明/市场Marketplace模块.md §1-§2，源码确认级）

5.1 审核策略管理（管理员最重要的市场操作）

🔴 auto-approve 默认开启：`is_auto_approve_enabled = true`（默认自动通过）——默认配置下任何人提交的插件都会自动上架。企业部署若有上架安全要求，必须由 Space owner / admin 显式 PATCH 关闭 auto-approve，改人工审核流程（人审队列：submit / list / approve / reject / cancel；审批回调支持 IM 卡片，HMAC 签名防伪造）。（来源：Marketplace模块.md §3.3，源码确认级）

部署后第一件事：检查并按需关闭自动审核，改人工审核；
若保留人审：定期处理 pending 队列（approve/reject）；
对外采购/自研插件上架走统一发布链路（init 上传→解析元数据→提交发布）。

5.2 可见范围（visibility 四档）

visibility	可见范围	用途
`public`	公开市场，所有 Space 可见	全企业共享
`space`	Space 级私有，仅当前 Space 成员可见	企业私有市场（推荐）
`private`	仅 owner 可见	个人草稿/试验
`system`	系统内置（官方发布标识）	平台官方插件

5.3 评分与统计

🔴 评分是管理员打分，不是用户众评：市场评分是单字段 `rating TINYINT（1-5）`，仅管理员经 `PATCH /admin/plugins/:id/rating` 设置；不存在用户评分或评论功能。客户问"用户评分在哪看"，如实告知当前版本不支持。（来源：Marketplace模块.md §7.1，源码确认级）

5.4 版本与安全注意

已发布版本 = 不可变快照，版本号强制 SemVer 且只能升不能降（VersionNotRegressed）；current 与 in-review 版本可并存。
Marketplace 本身不运行插件（纯分发/目录服务）；插件运行在 Fleet（expert/expert_team 云端编排）或本地 runtime（skill/connector）。
🔴 运行期沙箱能力待确认，不得声称"插件完全沙箱隔离"：seccomp/容器沙箱、宿主文件系统/网络白名单、显式权限声明模型、制品安全扫描均为 P0 待确认项（位于 Fleet/octo-daemon 私有仓）。对内表述口径："分发层鉴权完备（API Space 强隔离/签名 URL 下载/SHA256 完整性校验），运行期沙箱能力待确认"（来源：Marketplace模块.md §6）。
灰度 canary / 一键回滚 / 配置迁移机制未找到（待私有仓确认），插件升级以"发布新版本"为主，回退版本号不允许——上线前充分测试。

六、系统设置

6.1 注册与登录

配置项	默认	说明
`register.off`	true	是否关闭公开注册（默认关闭）
`register.only_china`	—	仅中国手机号可注册
`register.username_on` / `register.email_on`	—	是否开启用户名/邮箱注册登录
`login.local_off`	—	是否关闭本地账号登录入口（纯 SSO 场景用）
`login.scan_enabled`	默认关闭	是否开启扫码登录（Octo 自有 IM 扫码，非企微/钉钉/飞书扫码）
`login.manager_email_mfa_on`	默认关闭	管理控制台邮箱二次验证（见 §1.5）

6.2 文件与贴纸（高频调整项）

配置项	默认	说明
🔴 `file.max_size_kb`	102400（100MB）	单文件上传上限（KB）。硬顶 512MB（部署侧 env `OCTO_FILE_MAX_SIZE_KB_HARD_CAP` 决定，未配置时 524288；配置超硬顶会被钳到硬顶）。调整后注意 nginx `client_max_body_size` 同步放大（来源：07-faq-troubleshooting/常见问题排查FAQ-v1.0.md §3.1）
`file.extra_blocked_extensions`	—	额外禁止上传的扩展名（与 env 取并集，只增不减；内置黑名单约31种不可撤销；跨实例 60s 收敛）
`file.extra_allowed_extensions`	—	额外允许的扩展名（只能收窄白名单；要收回写进 blocked）
`sticker.upload_max_size_kb`	1024（1MB）	自定义贴纸单文件上限（服务端硬顶 5MB；实际生效=min(本值, file.max_size_kb)）
`sticker.upload_max_dimension`	512	贴纸单边像素上限（硬顶 1024）
`sticker.custom_enabled`	—	是否展示自定义贴纸管理入口

文件安全双重校验：扩展名白名单+黑名单 + 魔数校验（改后缀伪装会被拦截）；空扩展名直接拒绝【✅源码确认】。

6.3 Bot 限流（botratelimit）

桶	默认 rps / burst	说明
`business`	20 / 200	业务端点（sendMessage 等）主配额。默认 enabled=false + dry_run=true（影子观察模式，只观测不拦截）——即默认不启用 per-bot 限流，先观察定配额
`heartbeat`	1 / 10	心跳保活通道（rps 读侧下限 0.1，防止保命通道自断）
`register`	0.5 / 10	换 token/注册通道（burst 被 clamp 到 rps×20）

botcard.display_enabled / interaction_enabled / reasoning_enabled：展示卡/交互卡/推理进度卡的服务端总闸（受卡片总闸 OCTO_CARD_MESSAGE_ENABLED 支配；🔴 本地卡片开关已废弃，能力以服务端 manifest 下发为准——来源：售前红线卡 R7）。
app_bot.auth_cache_ttl_seconds：App Bot 鉴权缓存兜底 TTL，有效范围 [30,600]，默认 60s（吊销经墓碑即时生效，此值仅兜底）。

6.4 功能模块开关（客户端入口）

配置项	默认	控制
`docs.enabled`	关闭	Web「文档」入口（octo-docs-backend 上线前默认关闭）
`docs.search_enabled`	关闭	云文档全文搜索入口（与 docs.enabled 解耦，需 doc-index 就绪）
`drive.enabled`	关闭	Web「网盘」入口（仅 Web 端，移动端未实现）
`drive.search_enabled`	关闭	搜索"网盘"tab（需 drive-index+Tika 就绪）
`dmloop.enabled`	关闭	Web「回路」入口（仅 Web 端，移动端确认无回路）
`dmpersonal.enabled`	关闭	「我的/运行时」入口（与 dmloop 分开独立放量）
`project.enabled`	关闭	项目(Project)协作模块
`mail.enabled`	关闭	Agent Mail 模块入口
`search` 系列	—	全文搜索为 opt-in（Kafka+OpenSearch 默认关闭，开启才需要）

⚠️ 端侧差异提醒：文档/网盘/回路/我的仅 Web 端可用，语音全端但首次使用需用户 opt-in（设置→语音设置确认协议；单条语音≤60s/3MB）；管理员开启模块前请同步告知用户端侧限制（来源：04-user-manual/普通用户快速上手指南.md §6.5）。

6.5 其他常用设置

space.disable_user_create：关闭普通用户建 Space 入口（见 §2.3）。
thread.auto_archive_enabled / auto_archive_days：子区不活跃自动归档。
incomingwebhook.*：入站 Webhook 总开关 + 每 webhook rps/burst + 每群/子区/创建者数量上限 + 成员是否可广播 @所有人。
onboarding.space_welcome_* / group_welcome_enabled：新成员入 Space/入群欢迎语。
support.email / email_smtp / email_pwd（加密存储）：技术支持邮箱 SMTP——开启管理端 MFA 前必须配置。
message_reaction.read / write：消息 Reaction 展示/操作入口。

七、运行时监控与日志

本章为管理员视角速览。完整 19 个服务健康端点表、metrics 接入、ELK/Grafana 方案、告警规则见《[监控与日志配置指南-v1.0](../03-deployment-ops/监控与日志配置指南-v1.0.md)》，此处不重复展开。

7.1 健康检查

octo-server 唯一健康端点：GET /v1/ping，返回 {"status":"ok"}【✅源码确认；compose healthcheck 即 wget http://localhost:8090/v1/ping】。/v1/health（限流豁免）与 /v1/ready 在部署 FAQ 中有提及，但常见问题排查FAQ v1.0 标注"独立探针路由待 Owner 确认"——日常以 /v1/ping 为准。
宿主机侧验证：curl -fsS http://127.0.0.1:28080/v1/ping（经 nginx）。
一键看全部服务健康：docker compose ps；仅看 unhealthy：docker inspect --format '{{.Name}} {{if .State.Health}}{{.State.Health.Status}}{{end}}' $(docker compose ps -q) | grep -v healthy。
核心七件套：octo-server / web / admin / WuKongIM / MySQL / Redis / MinIO——任一 unhealthy 优先处理。
WuKongIM 健康检查探测其 /route 或 /health（带 managerToken）；scripts/healthcheck-api.sh 探测的是 WuKongIM 而非 server（常见误区，来源：常见问题排查FAQ-v1.0.md §2.3）。

7.2 日志与日志级别调优

容器日志：docker compose logs -f octo-server / --tail=200 -t；建议在 /etc/docker/daemon.json 配置 json-file 轮转（max-size/max-file）防磁盘打满。
octo-server 日志级别 1-4（configs/octo-server.yaml 的 logger.level）：

级别	含义	建议
1	debug	默认（日志量大，影响性能）
2	info	生产推荐
3	warn	生产可选（更安静）
4	error	只看错误

mode: release 建议（生产避免 Gin debug 输出）；WuKongIM 生产建议 WK_MODE=release；octo-fleet 日志级别 FLEET_LOG_LEVEL（默认 info）；redis 启动参数固定 warning。（来源：监控与日志配置指南 §1.2）
nginx 访问/错误日志在 nginx-logs 卷（access.log 格式 main / error.log notice）。
排障关键词：panic、error、failed（重点：failed to ping MySQL、migration 失败 panic）。

7.3 Prometheus Metrics

🔴 metrics 默认不开：需设 DM_METRICS_ENABLED=true 后 octo-server 监听 :9090（DM_METRICS_ADDR 可覆盖），仅暴露 /metrics 一个路径【✅源码确认：main.go startMetricsScrapeServer】。指标全家桶一次抓取拿全（HTTP dmwork_http_* / 依赖 / 连接池 / Bot 限流等）。
MinIO 原生 metrics：:9000/minio/v2/metrics/cluster；WuKongIM monitor 端口 25300（/metrics 路径格式部署后实测验证）；MySQL/Redis 建议补官方 exporter；OpenSearch 需另装 Prometheus 插件（当前未配）。
compose 栈不内置 Prometheus/Grafana，需另行部署（node_exporter + cAdvisor + 各中间件 exporter；告警阈值建议与告警规则清单见监控指南 §4/§6）。

7.4 常用运维命令速查

docker compose ps                                # 全部服务健康状态
docker compose logs -f octo-server nginx mysql redis wukongim minio   # 跟踪核心日志
docker compose restart octo-server               # 重启单服务（配置变更后）
docker compose exec octo-server sh               # 进入容器排查
docker stats                                     # 容器资源实时
docker system df -v && df -h                     # 磁盘占用（含卷）
curl -fsS http://127.0.0.1:28080/v1/ping         # server 健康检查

八、安全管理

8.1 交付即检查清单（安全基线）

#	检查项	口径
1	🔴 Redis 必须设密码	生产强制（`.env` redisPass）；OOTB 只绑 127.0.0.1 默认空密码（来源：售前红线卡 R2 + 部署FAQ Q5）
2	🔴 MySQL 8.x + utf8mb4	字符集 utf8mb4 是硬要求，不支持"utf8 就行"（来源：售前红线卡 R1）
3	🔴 生产锁具体镜像 tag	禁止 latest；后端锁 release tag、Web 锁日期版本、插件锁 SemVer（来源：售前红线卡 R12 + 部署FAQ Q3）；changelog.md 节标题滞后，以 GitHub Releases 为准
4	端口最小暴露	对外仅开 28080（HTTP）/ 28443（HTTPS）；内部服务端口全部 bind 127.0.0.1；前置反代时设 `OCTO_NGINX_BIND=127.0.0.1`（来源：部署FAQ Q20/Q2）
5	🔴 MinIO downloadURL 必须对外可达	客户端直连 MinIO 下载文件，不经 server 代理——MinIO 不暴露则文件打不开（来源：售前红线卡 R11）
6	HTTPS 四地址同步	`MINIO_SERVER_URL` / `TS_MINIO_DOWNLOADURL` / `TS_EXTERNAL_BASEURL` / `OCTO_WK_WSS_ADDR`（必须 wss://）全配 HTTPS，否则 mixed-content/SigV4 签名错误（来源：部署FAQ Q2）
7	CORS	未配 `DM_CORS_ALLOWED_ORIGINS` = 禁用跨域（只允许同源）；按需配 origin 白名单（来源：部署FAQ Q9）
8	管理端 MFA	开启 `login.manager_email_mfa_on`（默认关，建议生产开启，先配好 SMTP）
9	speech-admin	仅 loopback + SSH 隧道访问，独立 ADMIN 账密/JWT（来源：部署FAQ Q17）
10	部署版本含 PR#713 修复	跨租户读漏洞已修复（4 处 pin/strip）；部署 v2026.09 之后版本，不部署过旧版本（来源：权限模型与鉴权体系.md §4.3）

8.2 租户隔离与合规口径

🔴 同库逻辑隔离（红线③）：所有 Space 共库共表共索引，靠 space_id 强制过滤 + 多层 fail-closed guard（SpaceMiddleware / OpenSearch 强制 term filter OCTO_SEARCH_REQUIRE_SPACE_ID / 防枚举统一 NOT_FOUND / uk_* API Key 冻结绑定单一 Space）。
🔴 强合规（金融/政企/涉密）走"一客户一部署"：独立数据库 + 独立 OpenSearch + 独立 MinIO bucket（或独立 MinIO）+ 独立服务副本。不要在同实例内承诺"强物理隔离"。
对外安全表述边界：隔离保证来自代码层 guard，可如实说明"历史漏洞 PR#713 已修复 + 搜索层 fail-closed"；不得进一步承诺"物理隔离/绝对安全"。

8.3 凭据管理

Bot token：永不过期（🔴 §4.3），泄露必须手动 revoke；App Bot 吊销经墓碑即时生效。
密钥类 env（JWT_SECRET ≥32hex、LOOP_CREDENTIAL_HMAC_KEY ≥32hex、COLLAB_TOKEN_SECRET ≥32hex 等）部署 preflight 强制校验非空/非 CHANGE_ME（来源：部署FAQ Q13 + 回路Fleet模块.md §2.5）。
support.email_pwd 为加密存储类型（encrypted），管理后台写入后不回显明文。

8.4 审计与留痕

插件版本 plugin_versions 不可变快照 + append-only（谁发了什么版本可追溯）。
管理端登录有独立限流与 MFA 端点；nginx access.log 可审计访问来源。
⚠️ 完整的"管理员操作审计日志"（谁在后台改了什么配置）未见已确认的独立审计模块——如客户有等保审计要求，以交付方案评估（如接 ELK 分析 nginx+容器日志），不要承诺产品内置完整审计报表。
升级前必须全量备份 MySQL（迁移自动执行、失败 panic，回滚靠备份，见 §9.1）。

8.5 证书更新

HTTPS 证书在反代/栈内 nginx 侧更新；Fleet 自签 webhook 证书挂载 ./certs/fullchain.pem（重启 fleet 生效；来源：回路Fleet模块.md §2.1）。
证书轮换后检查 §8.1 第 6 项四个地址一致性。

九、常见管理问题 FAQ

详细排查步骤（含命令）见《[常见问题排查FAQ-v1.0](../07-faq-troubleshooting/常见问题排查FAQ-v1.0.md)》，此处收录管理员最高频问题与指路。

Q1：服务起来就 panic / 容器循环重启怎么办？

Q2：用户反馈登录不上？

账号是否被禁用（查封禁列表，§3.2）；
是否开了 SSO 且 `login.local_off`（本地入口被关）；
密码问题 → 管理员重置密码（无公开自助找回）；
SSO 报错 → 检查 OIDC 配置（`DM_OIDC_ENABLED` 等，disabled 时端点返回 404）；SAML/LDAP 不支持，需 Keycloak 等桥接（权限模型 §5.2）；
全局性登录故障 → 先打 `/v1/ping` 确认 server 活着（FAQ v1.0 §九流程图）。

Q3：Bot 突然不可用/不回消息？

401：token 错/前缀错（bf_ User Bot、app_ App Bot）/Bot 被禁用——单一反枚举码，逐项核对；
🔴 403 bot_unavailable：App Bot 未发布——去后台发布（§4.4）；
403 not_group_member：Bot 不在群里——拉群；
429：被限流——读 Retry-After 退避重试；同 IP 多 Bot 抢配额是历史事故模式（heartbeat 漏→Bot 离线）；
全部 Bot 离线 → 检查 server /v1/ping 与 /v1/bot/heartbeat 通道；
token 怀疑泄露 → 立即管理端 revoke（永不过期不会自愈，§4.3）。

Q4：文件上传失败？

Q5：搜索/文档/网盘/回路入口用户看不到？

Q6：想给某部门隔离一块空间？

Q7：用户说"我是管理员为什么改不了 XXX"？

十、附录：管理员速查表 + 相关文档索引

A. 管理员速查表

项	值
Web 端	HTTP 28080 / HTTPS 28443（K8s 走 Ingress 80/443）
管理后台	`/admin/`（仅管理员）
健康检查	`GET /v1/ping` → `{"status":"ok"}`
Metrics	`DM_METRICS_ENABLED=true` → `:9090/metrics`
WuKongIM	TCP 25100 / WS 25200 / API 25001(内)/5001(容器) / monitor 25300 / gRPC webhook 6979

任务	去哪做
建/禁用户、重置密码、封禁	管理后台→用户管理（§3.2）
建 Space、强制加/移成员、邀请链接	管理后台→Space 管理（§2.2）
建 User Bot	客户端私聊 BotFather `/newbot`（§4.2）
建 App Bot 并发布	管理后台/管理端 API（§4.4，未发布=403）
吊销 Bot token	管理后台机器人管理 revoke_token（§4.3）
关插件自动审核	Space owner/admin PATCH auto-approve（🔴 默认开，§5.1）
调文件大小上限	系统设置 `file.max_size_kb`（默认100MB/硬顶512MB，§6.2）
开文档/网盘/回路入口	部署 profile + `docs/drive/dmloop.enabled`（§6.4）
调 Bot 限流	系统设置 botratelimit 三桶（business 20/200 默认 dry-run，§6.3）
看日志/健康	docker compose logs / ps（§7）
升级	《升级与版本迁移指南》（先全量备份！）

#	硬口径	出处
1	无 organization，租户边界唯一是 Space	§1.3/§2.1/§9 Q6
2	无自定义 RBAC，角色硬编码	§1.3/§9 Q7
3	同库逻辑隔离非物理隔离；强合规一客户一部署	§1.3/§8.2
4	管理端复用 /v1/*，无独立 admin API/无 Swagger（R5）	§1.3
5	默认关闭公开注册	§3.1
6	Bot 是普通群成员非超管（G8/R3）	§4.5
7	解散群/改角色不对 Bot 开放（R4）	§4.5
8	Bot token 永不过期，仅手动重置	§4.3
9	App Bot 未发布=403 bot_unavailable	§4.4/§9 Q3
10	App Bot DM-only，无群聊能力	§4.4
11	市场≠BotFather；Bot 不经市场分发	§4.1/§5
12	Marketplace auto-approve 默认开启，需显式关闭	§5.1
13	评分=管理员 TINYINT(1-5)，非用户众评	§5.3
14	插件运行期沙箱能力待确认，不得称"完全沙箱隔离"	§5.4
15	Redis 生产必须设密码（R2）；MySQL 8.x utf8mb4（R1）；生产锁 tag（R12）；MinIO downloadURL 必须可达（R11）	§8.1
16	无官方性能基准，不承诺 QPS/并发/SLA（R10）——容量以 PoC 实测为准	§6.3 调优注

B. 相关文档索引

主题	文档
普通用户使用	[04-user-manual/普通用户快速上手指南](普通用户快速上手指南.md)
权限/鉴权/SSO 权威口径	[02-architecture/权限模型与鉴权体系](../02-architecture/权限模型与鉴权体系.md)
产品能力边界	[01-product/OCTO是什么](../01-product/OCTO是什么.md) · [核心能力概览](../01-product/核心能力概览.md)
市场模块	[01-product/模块说明/市场Marketplace模块](../01-product/模块说明/市场Marketplace模块.md)
回路/Fleet	[01-product/模块说明/回路Fleet模块](../01-product/模块说明/回路Fleet模块.md)
监控/日志（19健康端点表）	[03-deployment-ops/监控与日志配置指南-v1.0](../03-deployment-ops/监控与日志配置指南-v1.0.md)
部署 FAQ	[03-deployment-ops/部署FAQ-v0.1](../03-deployment-ops/部署FAQ-v0.1.md)
模块开启	[03-deployment-ops/内部模块Profile开启指南-v1.0](../03-deployment-ops/内部模块Profile开启指南-v1.0.md) · [环境变量配置参考-v1.0](../03-deployment-ops/环境变量配置参考-v1.0.md)
端口/防火墙	[03-deployment-ops/网络端口与防火墙清单-v1.0](../03-deployment-ops/网络端口与防火墙清单-v1.0.md)
备份恢复	[03-deployment-ops/备份与恢复指南-v1.0](../03-deployment-ops/备份与恢复指南-v1.0.md)
升级迁移	[03-deployment-ops/升级与版本迁移指南-v1.0](../03-deployment-ops/升级与版本迁移指南-v1.0.md)
故障排查	[07-faq-troubleshooting/常见问题排查FAQ-v1.0](../07-faq-troubleshooting/常见问题排查FAQ-v1.0.md)
Bot API 错误码	[04-api-integration/Bot-API错误码与排障-v1.0](../04-api-integration/Bot-API错误码与排障-v1.0.md)
售前红线	[08-presales-delivery/售前红线卡-v1.0](../08-presales-delivery/售前红线卡-v1.0.md)
部署/验收	[私有化部署Checklist-v1.0](../08-presales-delivery/私有化部署Checklist-v1.0.md) · [交付验收标准模板-v1.0](../08-presales-delivery/交付验收标准模板-v1.0.md)

C. 待确认项（本手册范围内）

项	状态	影响
管理后台各页面/菜单具体布局	待走查	全篇"以实际界面为准"
管理员手动改短号的 UI 入口	待确认（AUTH 类）	§3.3
`allow_view_history_msg` 是否暴露 Bot 配置 UI	待确认（AUTH-02）	§4.5
`/v1/health` `/v1/ready` 独立探针	待 Owner 确认	§7.1
完整管理员操作审计日志模块	未见证据	§8.4
marketplace Helm 默认 enabled 与前端 API 路径	待确认（P2）	§5
business 限流桶默认 20/200 为 dry-run 观察值，生产启用前建议实测	已确认默认值	§6.3

状态水印：v1.0 draft | 更新 2026-09-22 | confidence: medium | 管理功能基于产品能力文档+octo-server源码已确认后端能力整理（标注【✅源码确认】处有源码依据），UI 细节以实际产品为准；硬口径引用16处全部对齐知识库 active/确认级文档；未走查产品验证，不适用于直接客户分发；reviewer: 待田文标确认。