管理面板

管理面板是面向平台运维人员的系统级界面，不属于任何工作区——管理员可以跨整个 Mopheus 实例管理用户、系统配置和功能开关。

管理面板与工作区级 Admin 角色不同。工作区 Admin 可以管理工作区内的成员和设置；系统管理员管理的是整个平台。

访问管理面板Copy Anchor Link

在浏览器中访问 /admin。只有拥有系统管理员角色的用户才能进入此区域，非管理员用户会看到 403 错误。

管理面板包含七个标签页：

首个管理员用户Copy Anchor Link

首次启动时，Mopheus 会根据环境变量自动创建管理员账户：

如果该邮箱的用户已存在，Mopheus 会将其提升为管理员，而不是创建新账户。

重要： 首次登录后请立即修改默认密码。

用户管理Copy Anchor Link

用户标签页列出所有注册账户。在这里可以：

创建用户Copy Anchor Link

1. 点击 新建用户
2. 输入用户邮箱和姓名
3. 点击 创建

新账户没有初始密码。如果已配置邮件（SMTP），用户会收到一封包含密码设置链接的欢迎邮件。否则，请使用下方的密码重置流程。

发送密码重置Copy Anchor Link

1. 在列表中找到目标用户
2. 点击 发送密码重置 操作
3. 用户会收到一封包含重置链接的邮件

管理员无法直接设置或查看用户密码——重置邮件是唯一的密码恢复机制。

启用或禁用用户Copy Anchor Link

用户列表会显示每个账户的启用状态。通过用户操作菜单可以暂停账户访问，也可以稍后重新启用。禁用用户无法登录，且不会占用用户授权配额。

工作区成员角色Copy Anchor Link

管理端用户列表会为每个用户返回其已加入的工作区，以及在该工作区的成员角色 role 和可读的 roleName。运维人员无需离开管理面板即可查看用户在各个工作区的权限等级。

系统配置Copy Anchor Link

配置标签页展示所有系统级设置。每项设置的生效方式不同：

主要配置项Copy Anchor Link

通用：

• 站点名称 (site_name) — 平台显示名称
• 允许注册 (allow_registration) — 启用或禁用公开注册
• 邮箱验证 (require_email_verification) — 新账户是否需要邮箱验证
• 允许注册的邮箱域名 (allowed_email_domains) — 逗号分隔的域名列表，留空表示允许所有域名
• 服务端 URL (server_url) / 前端 URL (app_url) — 后端和前端 URL

邮件（SMTP）：

• 邮件提供商 (email_provider) — "smtp" 或留空（自动回退到日志）
• SMTP 主机 (smtp_host)、SMTP 端口 (smtp_port)、SMTP 用户名 (smtp_username)、SMTP 密码 (smtp_password)
• SMTP TLS (smtp_tls) — true 为隐式 TLS（端口 465），false 为 STARTTLS（端口 587）

邮件配置旁的快速设置会根据服务商预设填写 SMTP 主机、端口和加密方式。支持腾讯企业邮箱（smtp.exmail.qq.com:465，隐式 TLS）、QQ 邮箱（smtp.qq.com:465，隐式 TLS）、网易 163 邮箱（smtp.163.com:465，隐式 TLS）、阿里云企业邮箱（smtp.qiye.aliyun.com:465，隐式 TLS）、Gmail（smtp.gmail.com:587，STARTTLS）和 Microsoft 365（smtp.office365.com:587，STARTTLS）。仍可在邮件配置组中手动修改各项设置。

SMTP 账户请填写完整邮箱地址。如果服务商要求应用专用密码或授权码，请在密码栏填写该值，而不是邮箱的普通登录密码。发件人地址默认使用 SMTP 账户，也可以单独修改。Microsoft 365 需要为邮箱或租户启用 SMTP AUTH；此配置仅支持密码凭据，不支持 OAuth。

存储：

• 存储驱动 (storage_driver) — "local"、"s3"、"oss"、"obs"、"cos" 或 "minio"
• S3 兼容存储设置：S3 Bucket (s3_bucket)、S3 Region (s3_region)、S3 Endpoint (s3_endpoint)、S3 Access Key (s3_access_key)、S3 Secret Key (s3_secret_key)
• 私有 Bucket (s3_private) — 启用后，附件使用短期签名下载地址或 API 代理，不会使用公开对象 URL。S3 兼容驱动必须同时配置 Bucket、Endpoint、Access Key 与 Secret Key；修改任意存储设置后需重启服务。
• S3 CDN 域名 (s3_cdn_domain) — 可选的公开 CDN 主机名，仅用于附件下载；上传始终走 S3 API Endpoint。
• 本地设置：本地存储目录 (storage_local_dir)、本地存储基础 URL (storage_local_base_url)

阿里云 OSS 私有 BucketCopy Anchor Link

Mopheus 通过 AWS S3 API 访问 OSS。先将 Bucket ACL 设置为私有，为 RAM 用户创建仅限该 Bucket 的对象读取、写入、列举和删除权限，再填写以下存储配置。请将 cn-beijing 同时替换为 Bucket 的实际地域。

storage_driver = oss
s3_bucket = mopheus-dev
s3_region = cn-beijing
s3_endpoint = https://s3.oss-cn-beijing.aliyuncs.com
s3_access_key = <RAM AccessKey ID>
s3_secret_key = <RAM AccessKey Secret>
s3_private = true
s3_cdn_domain =

OSS 的 S3 兼容 Endpoint 格式为 https://s3.oss-{region}.aliyuncs.com，不是 Bucket 域名，也不是 OSS 原生 Endpoint。OSS 使用 virtual-hosted addressing，请求会发送到 <bucket>.s3.oss-{region}.aliyuncs.com。若 Mopheus 部署在同地域阿里云内网，上传可使用 https://s3.oss-{region}-internal.aliyuncs.com。浏览器无法访问内网 Endpoint，下载会经 Mopheus API 代理。请填写包含 https:// 的完整 Endpoint URL，保存这些设置后必须重启服务。

华为云 OBS 私有 BucketCopy Anchor Link

先将 OBS Bucket ACL 设置为私有，为 IAM 用户授予该 Bucket 的对象读取、写入、列举和删除权限，再填写 Bucket 实际地域对应的 Endpoint。Endpoint 必须包含 https://。

storage_driver = obs
s3_bucket = mopheus-dev
s3_region = cn-north-4
s3_endpoint = https://obs.cn-north-4.myhuaweicloud.com
s3_access_key = <IAM Access Key>
s3_secret_key = <IAM Secret Key>
s3_private = true
s3_cdn_domain =

OBS 必须使用 virtual-hosted addressing，Mopheus 会将请求发送到 <bucket>.obs.{region}.myhuaweicloud.com。OBS 不支持 path-style URL。保存设置后必须重启服务。

本地 MinIOCopy Anchor Link

启动 MinIO 并创建 Bucket 后，将 S3 API 端口（9000）配置到 Mopheus。9001 是 MinIO 管理控制台端口，不能填入 s3_endpoint。

storage_driver = minio
s3_bucket = it-bucket
s3_region = us-east-1
s3_endpoint = http://127.0.0.1:9000
s3_access_key = mopheus-it
s3_secret_key = mopheus-it-secret
s3_private = true
s3_cdn_domain =

如果浏览器可以访问 MinIO 主机，请将 127.0.0.1 替换为对应主机名或物理 IP。运行可选的研发集成测试时，设置 MINIO_ENDPOINT、MINIO_BUCKET、MINIO_ACCESS_KEY 和 MINIO_SECRET_KEY，再使用 integration 构建标签运行测试；未设置这些变量时测试会自动跳过。

任务清理：

• 智能体任务超时 (agent_task_timeout) — 运行中任务超时（Go duration，如 4h、24h）
• 派发超时 (dispatch_stale_timeout) — 已分派但未启动的任务超时（如 5m）
• 排队超时 (queue_ttl) — 排队任务最大等待时间（如 2h）

飞书集成：

• 启用飞书 (lark_enabled) — 开启飞书 Bot 集成
• 飞书 App ID (lark_oauth_app_id) / 飞书 App Secret (lark_oauth_app_secret) — 飞书开放平台凭据
• 飞书域名 (lark_domain) — "feishu.cn"（国内）或 "larksuite.com"（国际）
• 飞书密钥 (lark_secret_key) — 用于加密飞书应用凭据的 AES-256 密钥

LDAP / Active Directory 登录：

• 配置服务器 URL、传输模式、用户搜索 Base DN 和登录属性。可选搜索过滤器使用 {username}；留空时系统按登录属性生成过滤器。AD 同时匹配用户名和 UPN 时可填写 (|(sAMAccountName={username})(userPrincipalName={username}))。
• 将目录属性映射到 Mopheus 姓名和邮箱；邮箱必须有效。可选只读搜索账号需要同时配置绑定 DN 和密码。
• 加密连接请选择 STARTTLS 或 LDAPS，系统始终验证证书。只有明确选择明文模式时才会使用未加密 LDAP。
• 完整配置后再启用 LDAP。首次成功登录会创建本地账户，之后按规范化邮箱匹配；已禁用账户仍无法登录。LDAP 登录不会自动加入工作区，也不会同步目录组。
• 用户列表会记录账户创建来源：普通注册、飞书、邮箱验证码或 LDAP。LDAP 目录密码由目录服务管理，用户不能在 Mopheus 自助改密或重置；管理员可单独设置 Mopheus 本地密码。

密码登录身份验证器策略：

• 在身份验证器（totp_policy）中选择关闭、自愿绑定或强制绑定。强制策略下，尚未绑定的用户会在下次密码登录时完成绑定，不设宽限期。
• TOTP 仅在本地账号密码验证后执行。飞书 / Lark、邮箱验证码和 LDAP 登录不会要求身份验证器验证码。
• 用户可在设置 → 个人与账号 → 安全中绑定、更换或停用身份验证器。更换或停用时需要验证账号密码和当前身份验证器验证码。
• 用户丢失设备时，管理员可在用户 → 操作 → 重置身份验证器中重置绑定。重置会写入审计记录；配置 SMTP 后会发送邮件通知。强制策略下，用户下次密码登录时需要重新绑定。

功能开关Copy Anchor Link

功能标签页管理功能开关。每个开关有一个系统状态：

管理功能开关：

1. 打开功能标签页
2. 点击某个功能查看详情
3. 根据需要修改系统状态
4. 对于选定状态，管理工作区白名单

授权管理Copy Anchor Link

授权标签页展示整个安装实例的当前授权状态。如果尚未导入签名授权文件，Mopheus 会使用内置默认授权。

默认限制为：

导入的授权是签名授权码。申请和导入流程为：

1. 打开授权标签页
2. 点击下载授权申请，保存当前安装实例的授权申请码
3. 将授权申请码发送给授权服务方
4. 收到返回的授权码后，在授权标签页上传授权文件，或切换到粘贴方式直接粘贴授权码
5. 导入成功后，页面会显示新的授权状态和限制

授权页面还会展示预留限制，例如用户数、每工作区成员数、项目、技能、自动任务、代码仓库、运行时、API Token、打开工单、每月智能体任务运行次数、存储、附件、飞书安装、Webhook 集成和并发智能体任务。这些值会随授权签名并存储，即使某个限制暂时还没有在产品中执行。 数值 -1 表示不限制。

系统 Cron 观测Copy Anchor Link

系统 Cron 标签页从共享 PostgreSQL 快照中读取所有 API 进程的 15 个系统定时任务。每个进程默认每 60 秒发布一次有界快照。system_cron_observation_enabled 控制是否发布；system_cron_observation_interval_seconds 可设为 10 至 3600 秒。两项设置均支持热重载。启用 Redis 时，配置失效通知会传播到其他进程；未启用 Redis 时，现有配置轮询最长可能需要五分钟。实例快照在 PostgreSQL 中保留七天；页面显示全部新鲜活跃进程和最近报告的最多 100 个历史进程。

每个任务在内存中保留最近五次运行、五次失败和最多 60 个分钟计数桶。成功运行不会逐次写入数据库。运行数和失败数按进程启动周期累计。completed 表示 callback 已返回，不保证内部每一步都成功。panic 会记录为失败运行，调度器随后继续；失败摘要和 cron 日志不会包含原始错误或 panic 文本。

每次进程启动都会生成新 ID。超过三个报告周期没有数据库快照时，页面显示进程失联；优雅关闭会标记为已停止，异常退出则会变为失联。关闭观测后，页面会把已发布快照标为历史数据。多服务部署中的任意管理员 API 实例都会从 PostgreSQL 读取相同的进程列表。

管理员可以请求由处理该请求的 API 进程运行任务。接受响应只表示本地已接收派发请求，不代表任务已完成或成功。运行或跳过结果会出现在后续快照中，最迟不超过配置的报告间隔（默认 60 秒）。

管理端 API 分页Copy Anchor Link

只有数据量持续增长、上限无法预估的列表才分页。规模有界的集合在一次请求中返回全部内容，响应中不带 meta 对象。

分页接口接受两个查询参数：

分页接口返回统一响应信封 { success, data, error, code, requestId, meta }。其中 meta 描述整个过滤结果集，而不只是当前返回的这一页：

{
  "page": 1,
  "perPage": 50,
  "total": 120,
  "totalPages": 3
}

以下接口已分页：

以下接口不分页，一次请求返回整个集合，响应中也没有 meta 对象：

单对象和聚合接口保持原有语义，不分页：GET /api/v1/admin/stats、GET /api/v1/admin/license、GET /api/v1/admin/license/request、GET /api/v1/admin/config/:key、GET /api/v1/admin/features/:key、GET /api/v1/admin/workspaces/:id、GET /api/v1/admin/workspaces/:id/features、GET /api/v1/admin/template-requests/:id/source 和 GET /api/v1/admin/templates/:id。

平台可观测性Copy Anchor Link

三个只读接口用于展示平台运行时活动。运行时清单和守卫事件日志分页，用量趋势不分页，因为它的数据点数量由天数窗口限定。

运行时清单Copy Anchor Link

GET /api/v1/admin/runtimes 返回全平台运行时清单。两个可选过滤条件用于缩小范围：

响应包含整个过滤结果集的 total、online、offline、busy、error 计数，以及分页的 items 列表。每个条目包含运行时 ID、工作区 ID/名称/slug、daemon ID、设备名称、运行时名称、provider、运行时版本、CLI 版本、状态及其可读的 statusName、enabled 标志、最近心跳时间，以及运行中和排队中的任务数量。

用量趋势Copy Anchor Link

GET /api/v1/admin/stats/trends 按天升序聚合 usage_runtime_daily。可选参数 days 指定统计窗口（默认 30，范围 1-365），可选参数 workspaceId 将结果限定到单个工作区。每个数据点包含日期、智能体任务总数、完成数、失败数、总耗时（毫秒），以及输入、输出、缓存读取和缓存写入的 token 数量。窗口最多覆盖 365 个数据点，因此该接口一次返回窗口内的全部数据点，不接受 page 和 perPage 参数。

守卫事件Copy Anchor Link

GET /api/v1/admin/stats/guard-events 将运行时守卫事件与其工作区关联。它接受相同的可选 days 和 workspaceId 参数，返回告警与熔断计数、按工作区拆分的明细，以及分页的近期事件。

工作区统计Copy Anchor Link

GET /api/v1/admin/workspace-stats 每个工作区返回一行数据。整个矩阵在一次请求中返回，不分页，响应中没有 meta 对象。每行还包含 ticketCount、projectCount、storageBytes，以及该工作区已注册的运行时节点列表。

管理员 CLICopy Anchor Link

发布包会为 mopheus-admin 提供独立归档；部署安装器不会安装它，运维人员需要单独安装二进制并加入 PATH。已安装的 admin CLI 使用 mopheus-admin upgrade 更新。普通 mopheus 二进制不会注册管理员命令。

管理员凭据默认保存在 ~/.mopheus-admin，也可使用 MOPHEUS_ADMIN_CONFIG_DIR 指定根目录、使用 MOPHEUS_ADMIN_PROFILE 隔离 profile；MOPHEUS_ADMIN_SERVER_URL 和 MOPHEUS_ADMIN_TOKEN 可覆盖保存值。登录会校验管理员角色，工作区 JWT 和 moc_task_* 任务 Token 访问 Admin 路由都会被拒绝。

只有调用分页接口的子命令支持 --page 和 --per-page：mopheus-admin user list、mopheus-admin workspace list、mopheus-admin template <type> list、mopheus-admin template category list、mopheus-admin template request list、mopheus-admin template skill file list、mopheus-admin stats runtimes 和 mopheus-admin stats guard-events。这些命令在结果超过一页时会在表格输出末尾打印分页页脚（Page <n>/<total>, <n> items total (use --page to see more)）；JSON 输出保留 data 与 meta 信封，便于脚本读取分页元信息。

调用不分页接口的子命令没有分页参数，也不打印分页页脚：mopheus-admin config list、mopheus-admin feature-flag list、mopheus-admin stats workspaces、mopheus-admin stats storage、mopheus-admin stats trends 和 mopheus-admin system-cron list。它们的 JSON 输出是原始载荷，不带 data 与 meta 包装。

命令组包括 user、license、stats、system-cron、feature-flag、workspace、config、template 和 upgrade。每种模板使用独立命令组管理，例如 mopheus-admin template skill create|list|get|update|delete；skill 文件操作位于 mopheus-admin template skill file。使用 mopheus-admin template skill|agent|team save-as-template 将现有资源直接发布为全局模板。使用 mopheus-admin template request list 查看全部申请，show <request-id> 检查技能正文和所有附属文件，再用 approve 或 reject --review-note 记录审核结果；拒绝理由必填。成员先用 mopheus skill request-save-as-template 提报，管理员审核后发布，目标工作区再通过模板 preview/apply 接口预览并应用。

新增和变更的子命令：

LDAP 测试密码仅转发给服务端用于绑定测试，不会回显。