系统配置
面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/app-configuration/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。
站点管理员通过 Console → 系统配置管理站点默认值、空间策略与共享运行参数。空间管理员继续使用 Pod 设置中已有的管理权限。
查找配置与选择范围
编辑前先选择站点配置与默认值或当前空间覆盖。页面始终显示数据空间名称。站点默认值影响所有未设置覆盖的空间,不代表空间参数的强制上限。
默认使用按任务分组视图,相关参数在同一表单中编辑,列表显示启停、覆盖与生效状态。只读键值注册表展示所有已注册键与动态规则,注明作用域、值来源、加密状态和管理入口。搜索可以命中组合表单内部字段及旧键名,并打开、定位相应字段;具名管理链接可直达对应 Console 页面和 Tab。
站点级键按“已存站点值 → 代码默认值”解析。租户级键按“实际支持的 Agent 覆盖 → 空间覆盖 → 站点默认 → 代码默认”解析。Pod 级键只读取空间值和代码默认值。五个实际使用 Agent 覆盖的键提供只读查询,不提供 Agent 覆盖写入口。
修改与重置
在一个明确范围内编辑,确认单位后保存。组合任务整体提交,任一字段校验失败时整组不变,草稿保留。密钥默认掩码展示,需要明确操作才会解密。重置确认框直接显示当前值、移除覆盖后的实际值与来源。即使覆盖值等于默认值,删除覆盖与手动保存同值仍有区别:后者会继续保持独立覆盖。
时间字段支持可读单位换算,存储单位保持不变。输出上限区分“不显式限制”(null)和具体数值,无响应超时可显式关闭(0)。缩短删除保留期时,表单会说明永久清理后无法恢复的影响。
Trace 和 Control Plane Plugin 的“待重启”状态会保留到服务进程与已存配置一致。Brain 后台 Tick 每分钟检查共享 BM25 索引,并在分词器变化时重建;维护可能暂时影响检索或阻塞写入。失败时可查看 Brain 健康页与服务端 Tick 日志。
SMTP 表单可使用当前草稿试发,不修改正式邮件配置,也不创建验证码。未输入替代密码时保留已存密码。试发成功表示传输服务已接受邮件;修改草稿后,原试发结果会标记失效。
配置与环境变量
AppConfigure 将产品参数保存在 PostgreSQL,多数修改影响后续任务。部署环境变量提供启动所需基础设施参数;工具使用的自定义凭据请放入 Agent 环境变量。
当前内置的 AppConfigure 键
下表列出 Ankole 当前内置的 AppConfigure 配置键。Control Plane Plugin 还可注册更多扩展配置键,完整列表请以当前实例的系统配置页面为准。
Agent 运行
| 配置键 | 作用范围 | 用途 |
|---|---|---|
ai_agent.max_iterations |
租户 | 单个 Agent 回合内允许执行的模型迭代最大轮数 |
ai_agent.max_output_tokens |
租户 | 单次模型响应允许生成的最大输出 Token 数 |
ai_agent.inactivity_timeout_ms |
租户 | 模型或上游 Provider 持续无响应多少毫秒后终止当前回合 |
ai_agent.library.agent_plugin_defaults |
租户 | Agent Plugin 的默认启用状态映射 |
background_agent_jobs.max_running_per_agent |
租户 | 单个 Agent 允许并发运行的后台 Agent 任务上限;默认 3,有效范围为 1–64 |
sessions.wake_recycle |
租户 | 冷唤醒模型对话轮转阈值(默认 min_cold_gap_seconds: 3600、min_context_tokens: 128000、im_max_idle_seconds: 259200);当提示词缓存冷却且上下文体积较大,或外部 IM 会话跨多天静置后恢复时,自动轮转至新模型对话分支并注入受限的 <wake-briefing> |
Pod、Base、Applet 与 Drive
| 配置键 | 作用范围 | 用途 |
|---|---|---|
pod.allow_external_guests |
租户 | 是否允许受邀外部访客访问共享的 Pod 页面;默认 true |
pod.applet.limits |
租户 | Applet(小应用)运行限制(默认 timeout_ms: 60000、heap_mb: 128) |
pod.base.limits |
租户 | Base 查询与记录限制(默认 query_rows: 1000、record_bytes: 1000000、group_count: 1000、statement_timeout_ms: 5000) |
pod.office.limits |
租户 | Office 页面限制(涵盖电子表格、Word 文档与演示文稿):可在线打开编辑的最大文件体积(max_file_bytes: 20971520),以及将增量编辑写回文件的触发阈值(compaction_idle_seconds: 30、compaction_op_threshold: 100、compaction_structural_threshold: 10) |
drive.trash_retention_days |
租户 | Ankole 在自动彻底删除前保留已删除 Drive 节点的天数;默认 30,设为 0 时在修改此配置前无限期保留 |
drive.vfs_max_upload_bytes |
站点 | Worker /drive VFS 单文件最大上传字节数;默认 0 表示沿用底层对象存储上传上限 |
pod.ot_replay_window |
租户 | 为协同文档 OT 重放保留的最近变更批次数;默认 1000 |
pod.ocr_existing_scans |
租户 | 把上传时没有经过 OCR 识别的扫描版 PDF 页面送去识别;OCR 服务商按页收费;回收站中的 PDF(包括回收站文件夹里的)不送去识别;默认 false |
Workflow
| 配置键 | 作用范围 | 用途 |
|---|---|---|
workflow.max_concurrency_per_run |
租户 | 单次 Workflow 运行可申请的任务并发上限;默认 8,有效范围为 1–32 |
workflow.max_running_per_agent |
租户 | 单个 Agent 名下所有 Workflow 合计正在运行的任务总上限;默认 8,有效范围为 1–64 |
workflow.max_agent_calls_per_run |
租户 | 单次 Workflow 运行允许发起的子 Agent 调用上限;默认 32,有效范围为 1–1,024 |
修改上述参数会影响后续启动的 Workflow。单次运行可以申请更低的并发度或调用次数,但无法突破租户上限。更多执行细节与体积限制请参阅 Workflow。
Brain
Brain 使用租户的 ankole_brain 系统主体调用模型。在 Console 的模型配置编辑器中,可设置提取(light)、分析(heavy)、URL 获取(web_fetch)和重排(rerank)配置,并继承 Pod 与站点设置。
| 配置键 | 作用范围 | 用途 |
|---|---|---|
brain.enabled |
租户 | 是否启用 Brain 的知识检索、自动学习与后台维护;关闭后已存储的知识仍会保留 |
brain.embedding_model |
站点 | 向量检索使用的 Provider、模型与向量维度;留空将停用向量检索 |
brain.search_tokenizer |
站点 | BM25 全文检索分词器:icu、jieba、lindera_japanese 或 lindera_korean;修改后需重建 BM25 索引 |
brain.chunking |
租户 | Source 文档切片大小、相邻重叠字数与输入长度上限 |
brain.forgetting |
租户 | 各类记忆的时间衰减半衰期 |
brain.dreaming_task_cron |
租户 | 后台定期归纳整理知识(Dreaming)的 Cron 计划 |
brain.self_healing_task_cron |
租户 | 定期修复过期文档分块、向量嵌入与搜索索引投影的自愈 Cron 计划 |
brain.signal_channel_batch_idle_time |
租户 | 待学习的聊天消息批次在进入提炼流程前需静置的空闲秒数(会话结束时也会立即触发学习) |
brain.skill_learning_enabled |
租户 | 是否开启技能教训(Skill Lesson)的自动提炼与投递;关闭后已保存的教训仍会保留,但执行时暂不注入 |
brain.skill_learning_reflection_threshold |
租户 | 单个 Agent 触发一次技能教训反思前需累计的未消费 Signal Job 数量;最小值为 2 |
关于知识组织方式与模型配置要求,请参阅 Brain;关于随 Skill 动态注入的过程经验机制,请参阅技能教训。
AI Gateway 与可观测性
| 配置键 | 作用范围 | 用途 |
|---|---|---|
ai_gateway.compaction |
站点 | 对话历史自动压缩策略 |
observability.traces.enabled |
站点 | 下次启动控制面时是否开启进程级 OpenTelemetry 追踪导出 |
observability.traces.provider |
站点 | 追踪数据的语义投影格式:langfuse、langsmith 或通用 opentelemetry |
observability.traces.otlp_endpoint |
站点 | 启用追踪导出时使用的基础 OTLP/HTTP 端点地址 |
observability.traces.otlp_headers |
站点 | 启用追踪导出时使用的加密认证请求头 |
对接 Langfuse、LangSmith、VictoriaTraces 及其他 OTLP/HTTP 接收端的完整配置步骤,请参阅 LLM 可观测性。
免密邮箱验证码(Email OTP)与 Pod 登录策略
| 配置键 | 作用范围 | 用途 |
|---|---|---|
authn.email.mail |
站点,加密 | 用于免密 Email OTP 登录的站点级 SMTP 发信配置(含 server、from、port、ssl 及可选认证凭据);留空时停用 Email OTP |
authn.email.code_ttl_seconds |
站点 | 邮箱验证码的有效秒数;默认 600 |
authn.email.send_limits |
站点 | 共享发送时间窗口,以及邮箱、请求来源与 SMTP 渠道上限 |
authn.email.failure_limits |
站点 | 共享验证失败时间窗口,以及邮箱与请求来源的失败上限 |
principals.pod_login_policy |
租户,由其他页面管理 | Pod 工作区成员登录与邀请策略(allow_email_otp、allow_member_credential_change、allowed_email_domains、require_sso_for_members、allow_invite_links);在 Pod 设置中管理 |
身份、插件、特性开关和租户默认值
| 配置键 | 作用范围 | 用途 |
|---|---|---|
principals.identity_providers.active |
租户,只读 | 当前用于认证 Pod 工作区成员与管理员的已启用租户身份源;由 Pod 设置和身份源提供商页面维护 |
principals.identity_providers.directory_full_sync_interval_minutes |
租户 | 企业通讯录与组织架构的全量同步间隔(分钟) |
tenants.privileged_tenant_id |
站点,只读 | 持有 siteadmin 站点管理权限组的特权租户 ID |
plugins.enabled_ids |
站点,由其他页面管理 | 下次启动控制面时启用的 :optional 可选 Control Plane Plugin 列表(:always 插件随构建常驻启用) |
features.<flag> |
站点 | 驱动 OpenFeature 的特性灰度开关策略({enabled, percent, targets},Ankole.Features.Config) |
signals.show_dead_letter_error_details |
站点 | 向会话发送死信通知时,是否附带经截断与脱敏处理的 Session 回合报错详情;默认 false |
system.timezone |
租户 | 定时计划任务等控制面功能使用的默认时区 |
i18n.default_locale |
Pod | 当前 Pod 空间的界面、通知邮件与 Agent 消息默认语言;空间管理员也可在 Pod 设置中直接修改 |
Worker、网页读取和安全
| 配置键 | 作用范围 | 用途 |
|---|---|---|
agent_workers.ready_timeout_seconds |
站点 | Worker 实例处于未就绪状态的最长容忍秒数,超时后将挂载新缓存盘重建实例;默认 600(10 分钟) |
agent_workers.rendered_fetch_idle_ttl_ms |
租户 | web_fetch 内置浏览器渲染回退实例的空闲保留毫秒数 |
security.ssrf_filter |
站点 | 是否拦截由模型发起的对私网、环回地址、链路本地地址及 CGNAT 地址段的网络访问 |
无论 security.ssrf_filter 是否开启,云厂商实例元数据地址始终会被强制拦截。
agent_workers.ready_timeout_seconds 专门控制已拉起但迟迟未能就绪的实例自愈重建;而正常运行后的空闲实例回收时长,则在 Worker Provider 的 YAML 配置中通过 idleReleaseAfter 设定,详见 工作节点。
首次设置状态
| 配置键 | 作用范围 | 用途 |
|---|---|---|
setup.bootstrap_activation_code |
站点,只读 | 首次初始化页面校验使用的临时激活码 |
setup.completed |
站点,只读 | 标记当前实例是否已完成首次初始化 |
这两个状态键由初始化向导自动维护。如需查看初始化激活码,请在服务端执行 kit show bootstrap-activation-code,切勿尝试在系统配置页手动更改。
加密设置
包含敏感凭据的配置项在落盘时自动加密,并在列表页和编辑表单中脱敏掩码展示。编辑时若保留原有掩码不变,系统会继续沿用已保存的原值;只有输入新内容并点击保存,才会替换原值。
请仅在确有必要核对当前配置时点击“显示内容”,且切勿将明文凭据粘贴到聊天群、截图或公开工单中。