24. 常用配置的维护与变更

返回概览 · 完整版目录 · 下载完整 PDF

管理员不仅需要完成首次创建，还需要持续查询、调整、停用和清理平台对象。每次变更都应确认影响范围，保存后检查页面状态，并核对变更记录。“管理控制台 → 审计与合规 → 操作审计”页面需要“全链路审计”许可模块；模型供应商、模型服务、MCP 服务和外部智能体的详情中另有“操作审计”页签，记录该对象自身的变更。

24.1 维护管理角色、平台账号与登录会话

管理权限按职责分配，不把日常成员账号直接授予全部管理权限，也不多人共用同一个管理员账号。

租户管理角色

租户管理员从“管理控制台 → 组织与权限 → 角色管理”维护本租户六个内置角色的成员。角色职责、可见菜单、三员互斥规则和添加成员的步骤见第 3.4 节。日常维护按以下顺序进行：

1. 授予或调整角色后，使用该账号重新登录，检查管理菜单和允许动作，并确认无关页面不可访问。
2. 职责调整时先由接任人员验证权限，再对原人员选择“移除”。移除后该成员立即失去该角色的全部权限。

MCP 工具的调用权限在“路由策略”中以“工具名”“组织成员”等条件配置，不由管理角色决定。

平台账号

平台管理员专属。从“管理控制台 → 组织与权限 → 平台账号”为平台管理人员创建个人账号。平台账号为可选项，root 始终可以管理平台。

1. 选择“新建账号”，填写“姓名”“邮箱”，选择“登录方式”：“密码登录”会生成一次性激活链接，本人打开后设置密码并绑定两步验证；“仅单点登录”不生成激活链接，本人首次通过平台单点登录登录时按已验证邮箱自动绑定。
2. 需要授予全部平台管理权限时，选择“授予平台管理员”；收回时选择“撤销平台管理员”。
3. 人员暂时离岗时选择“停用”，其全部会话立即失效；确认不再使用后选择“删除”。激活链接过期时选择“重新生成激活链接”。

平台账号与 root 必须使用两步验证，不可关闭。

平台管理员从平台管理台右上角账号菜单打开「设置」，其中有「账号资料」「偏好设置」「账号与安全」「访问密钥」四个分区。「访问密钥」用于创建与撤销访问密钥，以签名方式调用平台管理接口与平台 MCP，权限与本人相同；密钥明文只在创建时显示一次。

登录会话与安全策略

从“管理控制台 → 组织与权限 → 账号与会话安全”进入。租户管理员看到本租户的会话，平台管理员看到全平台的会话。会话检索与撤销、“安全策略”各项设置及其取值范围见第 3.7 节。

平台管理员还可在“管理面访问网段”页签开启“仅允许以下网段访问管理控制台”，保存约 10 秒内所有实例生效。误配置导致无法进入控制台时，在安装主机执行 sudo zenova admin-network show 查看配置，用 sudo zenova admin-network allow --cidr <网段> 追加网段，或用 sudo zenova admin-network disable 关闭白名单；从安装主机本机回环地址访问始终放行。

登录事件、角色授予与移除记录在“操作审计”中查看（需要“全链路审计”许可模块）。

同步组织、维护部门并管理成员会话

租户管理员从“管理控制台 → 组织与权限 → 成员与部门”维护组织。页面包括“成员”“部门”“已离职成员”三个页签。

1. 在“成员”中按账号状态和部门筛选目标成员，核对现有归属。
2. 修改部门名称、负责人或上级部门前，查看该部门已获得的模型服务、MCP 服务、技能和外部智能体授权。
3. 调整成员所属部门或职能组后，让该成员重新登录，验证能力列表和管理菜单是否符合新职责。
4. 确认离职后删除成员，账号移至“已离职成员”，平台同时撤销其登录会话、刷新令牌与受信任设备，并吊销其 API 密钥与 MCP 访问令牌。成员丢失两步验证设备时，可为其“重置两步验证”，该操作同时让其所有会话失效。
5. 通过单点登录或目录同步维护组织时，从“管理控制台 → 组织与权限 → SSO 配置”的“已接入的身份源”选择“添加身份源”。可选的来源包括“钉钉”“飞书”“企业微信”“企业 IAM (OAuth2)”“LDAP”和“目录推送”。
6. 单次同步的变更量超过阈值时，变更暂存为“待复核”，由管理员“全部批准”或“拒绝”（见第 3.6 节）。LDAP 的分页大小在“检索范围”步骤设置。
7. 在“登录会话”和“操作审计”中检查账号状态、会话处理及组织变更。

同步来源的部门结构和成员关系在“成员与部门”中为只读，修改应在来源系统完成。组织调整完成的标志是：部门树正确、成员归属正确、授权范围随新归属生效，并且原范围不再可用。同步冲突时不要重复创建账号，应根据页面给出的用户名、邮箱或外部身份标识处理匹配关系。

24.2 维护模型供应商

从“管理控制台 → 搭建 → 模型供应商”进入供应商列表，打开供应商详情。详情包括“基本信息”“账号”“模型定价”“上游真实性”“可用性探查”“性能测试”和“操作审计”页签。

1. 在“基本信息”核对“请求地址”“模型请求格式”和已启用的模型；修改连接信息时选择“编辑 AI 供应商”，重新核对模型列表，只启用需要向当前组织提供的模型（见第 4.4 节）。
2. 在“账号”维护上游账号与 API 密钥。停用账号后立即不再接收流量；轮换密钥时先添加并验证新账号，再停用旧账号。
3. 在“可用性探查”选择“连通性测试”，查看结果、延迟和失败原因；连续失败时核对网络、凭据、协议兼容性和上游权限。
4. 在“模型定价”维护计价信息，在“操作审计”核对编辑和启停记录。
5. 删除模型前查看删除影响：页面列出引用该模型的模型服务、路由规则、API 密钥、定价记录等。被不可变路由规则引用时删除被阻止，需先修改这些规则（见第 4.9 节）。
6. 最后使用最小请求验证真实调用，并在调用记录中确认供应商、模型和状态。

保存成功只说明配置已经保存；连通性测试和真实调用均成功，才表示新的连接信息可以投入使用。凭据字段留空是否代表保留原值，以页面提示为准。

24.3 维护模型服务

从“管理控制台 → 搭建 → 模型服务”查询和维护成员实际使用的模型服务。详情包括“基本信息”“试跑”“可用范围与配额”“调用情况”和“操作审计”页签。

1. 在“基本信息”核对描述、模型列表和“发布”开关。
2. 编辑模型顺序或更换主模型前，检查目标模型已启用且供应商连接正常；修改后在“试跑”中发送一条测试请求。
3. 修改“可用范围与配额”后，分别使用获授权与未获授权账号验证列表和真实调用。
4. 暂停服务时关闭“发布”开关；恢复后执行一条最小请求，在“调用情况”确认状态和用量记录恢复。
5. 删除服务前处理 API 密钥、能力分发和路由中的引用。出现“暂不能删除模型服务”时，根据页面列出的引用对象完成迁移。
6. 变更后在能力中心检查服务名称、可见范围和实际可选状态。

需要提前告知成员模型服务下线时，可在“通知横幅”发布受众为“使用指定模型服务的用户”的公告，并设置到期动作“停用模型服务”，见第 23.9 节。

服务内某个模型不可用时，网关不会自动改用服务内的其他模型。需要失败时转到备用模型，在流量规则中配置故障转移（见第 15.7.3 节），并再次验证合规和调用结果。

24.4 维护 MCP 服务

从“管理控制台 → 搭建 → MCP 服务”进入，在“MCP 列表”中维护服务。

1. 使用名称或连接信息筛选服务，打开详情检查“发布”状态、连接方式、工具和“可用范围”。
2. 修改服务地址、Header 或鉴权方式后，重新执行“解析 Tools”。
3. 通过 OpenAPI、Postman Collection 或 cURL 更新由 HTTP 接口生成的工具时，检查新增、更新、冲突和未导入项，再保存工具目录。
4. 对工具名称、参数或说明进行调整后，使用有效参数和无效参数各执行一次测试。
5. 停止向成员提供服务时关闭“发布”或移除“可用范围”；两者承担不同作用，应分别核对。工具级的调用限制在“路由策略”中设置。
6. 删除服务前解除其他能力对它的引用，并确认没有仍在运行的调用。
7. 在详情的“调用情况”和“操作审计”中核对调用结果、耗时、使用者和变更记录。

连接验证成功但成员仍不可用时，依次检查发布状态、可用范围、有效期、成员组织归属、分发策略和凭据状态。

24.5 维护外部智能体服务

从“管理控制台 → 搭建 → 外部智能体”进入，页面包括“Agent 目录”和“任务中心”两个页签。接入、审批、上游凭据、调用方 Token、可用范围、发布为 MCP 工具和任务查询的完整步骤见第 12.1–12.4 节。日常维护按以下顺序进行：

1. 选择“立即探活”检查当前连通性；来源为名片 URL 时可重新拉取名片，检查端点、能力或鉴权声明是否变化。端点变更后凭据绑定会被暂存，需重新审批后才能再次注入。
2. 修改上游凭据或可用范围后，使用范围内与范围外的账号各验证一次。
3. 在“任务中心”按 Task ID 搜索任务，核对“目标 Agent”“调用方”“状态”和“耗时”。需要取消时选择“取消任务”；能否终止取决于对端实现，应确认任务实际进入“已取消”。
4. 删除前检查活动任务、调用方、路由及可用范围引用。删除后该 Agent 的网关调用凭据随之失效，此操作不可撤销。

接入完成的标志见第 12.4 节。

24.6 核对配置变更

对组织、模型、MCP 和外部智能体的重要变更使用同一套检查方法：

1. 记录变更对象、原因、影响范围、原值和预期结果。
2. 在页面中保存变更，确认状态不再处于等待、失败或未发布。
3. 使用一个获授权账号完成正向操作，再使用一个未获授权账号验证拒绝结果。
4. 在“概览”的“网关请求”页签或对象详情的“调用情况”中检查真实执行结果。
5. 在对象详情的“操作审计”页签或“操作审计”页面核对操作人员、对象、结果和时间。
6. 结果异常时恢复原配置，并保留请求标识和页面错误供排查。

24.7 接入新的模型与外部能力

新增模型供应商、MCP 服务、API 服务或外部智能体时，使用一致的接入顺序：

1. 确认能力用途、负责人、网络目标、认证方式和数据边界。
2. 在对应管理页面创建连接，凭据只填写在受保护字段中。
3. 执行页面提供的验证、模型获取、Tools 解析或连通测试，确认平台能够读取预期能力。
4. 配置模型服务、发布状态和可用范围，从试点部门或职能组开始授权。
5. 使用获授权账号完成真实调用，使用未获授权账号验证拒绝。
6. 在调用记录和变更记录中核对使用者、目标能力、结果与耗时。

接入多个同类能力时，应使用能够区分环境、用途和数据边界的名称，避免成员在能力中心选错。

24.8 变更访问地址与入口证书

平台管理员专属。平台的对外访问地址和入口证书从“管理控制台 → 平台扩展 → 网关”的“入口与证书”页签维护；入口端口与绑定网卡在“部署配置”中修改，见第 23.6 节。

修改公开访问地址

1. 在“公开访问地址”中填写“业务访问地址”。该地址供模型、MCP、A2A 等对外服务使用，网关入口域名与证书签发名由它的主机名派生。填写 http:// 或 https:// 开头的主机名或 IP，不带路径。
2. 按需填写“管理访问地址”。留空时使用业务访问地址的主机加管理入口端口。
3. 选择“保存”，在“确认修改公开访问地址”中核对变更前后的地址，选择“确认保存”。保存后立即生效：对外服务的端点与回调使用业务访问地址，控制台链接使用管理访问地址。
4. 需要回到安装时的地址时选择“恢复安装地址”。

修改访问地址前，应先在 DNS、负载均衡和防火墙中准备好新地址，并通知调用方更新端点和回调地址。

签发或上传入口证书

入口证书是覆盖入口域名的通配符证书，下发到所有网关节点入口。业务访问地址是 IP 地址时不能签发证书。

自动签发：

1. 在“自动签发证书”中开启“启用自动签发与续签”。“入口域名”由公开访问地址派生，不能单独修改。
2. 填写“DNS 托管域”，选择“DNS 服务商”（“Cloudflare”或“阿里云云解析”）并填写对应凭据。凭据需要该托管域的 DNS 编辑权限，保存后不再显示。
3. 按需填写“联系邮箱（可选）”，保存后选择“立即签发”。
4. 状态变为“已签发”后，核对“当前证书有效期至”。证书在到期前 30 天自动续签。

签发失败时，按页面原因处理：写入 DNS 验证记录失败时检查凭据权限与托管域；连不上证书颁发机构时检查控制面出网；域名验证未通过时等待 DNS 记录生效后重试。

手动上传：

1. 不使用自动签发时，在“手动上传证书”中粘贴“证书链 (PEM)”和匹配的“私钥 (PEM)”，选择“上传 / 替换证书”。
2. 在“当前证书”核对“主体备用名称”“过期时间”“SHA-256 指纹”和“节点入口下发”进度。

检查入口自检

在“入口自检”中核对“入口域名”“部署级通配符证书”和“来源 IP 规则可信代理配置”等项。有项目未就绪时按提示处理后重新自检；全部就绪后，从外部客户端通过新地址发送最小请求，在调用记录中核对结果。

---

上一章：23. 平台运行与日常维护 · 下一章：25. 分阶段上线