From 061f9971fd323cec430cc866501ebaa218977fe6 Mon Sep 17 00:00:00 2001 From: liudeshun <1209278955@qq.com> Date: Fri, 23 Oct 2026 10:56:04 +0800 Subject: [PATCH 01/26] feat(telegram): integrate host policies and native choices through Gateway --- CHANGELOG.md | 3 + dashboard/src/api/types/channel.ts | 21 + dashboard/src/locales/en.json | 27 + dashboard/src/locales/zh.json | 27 + .../Agent/Channels/ChannelsPanel.test.tsx | 65 ++- .../pages/Agent/Channels/ChannelsPanel.tsx | 11 +- .../Channels/components/ChannelDrawer.tsx | 48 +- .../Channels/components/constants.test.ts | 48 +- .../Agent/Channels/components/constants.ts | 122 ++++- docs/telegram.md | 17 + pyproject.toml | 4 + src/octop/i18n/domains/channel.py | 15 + src/octop/i18n/en.json | 16 + src/octop/i18n/zh.json | 16 + src/octop/infra/agents/manager.py | 19 +- src/octop/infra/errors.py | 2 + .../infra/gateway/channels/telegram_bridge.py | 376 +++++++++++++ src/octop/infra/gateway/gateway.py | 34 +- src/octop/infra/gateway/hitl/coordinator.py | 84 +-- .../infra/gateway/process/harness_request.py | 9 + .../infra/gateway/process/message_keys.py | 19 +- src/octop/infra/gateway/process/processor.py | 55 +- .../infra/gateway/process/response_mode.py | 10 +- .../infra/gateway/process/stream_project.py | 23 +- src/octop/infra/utils/stream_close.py | 7 + tests/unit/cron/test_cron_delivery.py | 55 ++ .../gateway/test_group_chat_regressions.py | 161 ++++++ tests/unit/gateway/test_harness_request.py | 24 + tests/unit/gateway/test_message_keys.py | 71 +++ tests/unit/gateway/test_stream_close_chain.py | 96 ++++ tests/unit/gateway/test_telegram_bridge.py | 498 ++++++++++++++++++ .../gateway/test_telegram_bridge_wiring.py | 38 ++ tests/unit/i18n/test_channel.py | 15 + uv.lock | 8 +- 34 files changed, 1958 insertions(+), 86 deletions(-) create mode 100644 docs/telegram.md create mode 100644 src/octop/infra/gateway/channels/telegram_bridge.py create mode 100644 src/octop/infra/utils/stream_close.py create mode 100644 tests/unit/gateway/test_group_chat_regressions.py create mode 100644 tests/unit/gateway/test_stream_close_chain.py create mode 100644 tests/unit/gateway/test_telegram_bridge.py create mode 100644 tests/unit/gateway/test_telegram_bridge_wiring.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 0bbbe4d43e..36865a6289 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,10 +8,13 @@ - Linux 桌面客户端无边框窗口支持拖拽边缘与角落调整大小。 ### 新增 +- Telegram 渠道可配置群聊触发、允许列表、话题隔离、流式与发送选项;模型菜单和单选问答使用原生按钮,由 Octop 在会话队列内重新校验权限与待答状态。 - 技能包支持「是否共享」:默认仅创建者可见,开启后其他用户可查看与挂载;创建时可同时设置复制策略与是否允许下载 - 技能包查看/编辑技能时展示左侧文件树(与个性化技能一致),并支持预览同级文件 ### 修复 +- Telegram 按钮操作入队后立即返回,停止响应会联动取消 Harness 执行;群聊新消息不会使仍有效的问答卡片失效,原生按钮发送失败时回退文字卡片。 +- Telegram 话题隔离保留旧会话与定时投递路由;引用在构造模型请求时按用户语言加入,命令和问答控制文本保持原文。 - 浏览器工作台支持中文等输入法组合输入与整段粘贴,恢复退格、删除、方向键和全选等编辑操作;提高预览刷新频率并减少重复的标签状态查询 - 回复还在生成时删除会话,会提示先停止再删,会话留在原地。不再在这一轮还在写记录时把会话删掉,从而把外键错误显示成「模型调用失败」 - 未登录、令牌无效或过期时,API 错误信息会按请求的 `Accept-Language` 语言返回(如中文返回「认证失败。」),不再固定英文;无请求头时保持原默认回退语言(#2187) diff --git a/dashboard/src/api/types/channel.ts b/dashboard/src/api/types/channel.ts index 18e226977c..1f5412427e 100644 --- a/dashboard/src/api/types/channel.ts +++ b/dashboard/src/api/types/channel.ts @@ -12,6 +12,26 @@ export interface DiscordConfig extends BaseChannelConfig { allowed_user_ids?: string[]; } +export interface TelegramConfig extends BaseChannelConfig { + bot_token: string; + http_proxy?: string; + group_activation?: "always" | "mention" | "mention_or_reply"; + allowed_user_ids?: string[]; + allowed_chat_ids?: string[]; + allow_unaddressed_commands?: boolean; + topic_isolation?: boolean; + reply_to_message?: boolean; + edited_messages?: boolean; + streaming_mode?: "off" | "auto" | "edit" | "draft"; + status_reactions?: boolean; + disable_notification?: boolean; + protect_content?: boolean; + link_preview?: boolean; + command_menu?: boolean; + albums?: boolean; + audio_as_voice?: boolean; +} + export interface DingTalkConfig extends BaseChannelConfig { client_id: string; client_secret: string; @@ -94,6 +114,7 @@ export interface OctopBotConfig extends BaseChannelConfig { } export interface ChannelConfig { + telegram: TelegramConfig; discord: DiscordConfig; dingtalk: DingTalkConfig; feishu: FeishuConfig; diff --git a/dashboard/src/locales/en.json b/dashboard/src/locales/en.json index 6e0cdf5e82..ae0d099b17 100644 --- a/dashboard/src/locales/en.json +++ b/dashboard/src/locales/en.json @@ -146,6 +146,7 @@ "STORAGE_BROWSE_FAILED": "Could not browse this storage backend.", "CHANNEL_KIND_UNSUPPORTED": "Unsupported channel type.", "CHANNEL_INVALID_CREDENTIALS": "Invalid channel credentials.", + "CHANNEL_OPTIONS_UNSUPPORTED": "Installed octop-gateway does not support these Telegram options. Install a compatible Gateway build before saving.", "CHANNEL_NAME_TAKEN": "This channel name is already in use. Please choose another.", "CONNECTOR_NOT_FOUND": "Connector not found.", "CONNECTOR_NAME_TAKEN": "This connector name is already in use. Please choose another.", @@ -2536,6 +2537,32 @@ "label_agentchat": "AgentChat", "label_xiaoyi": "XiaoYi", "label_mqtt": "MQTT", + "telegram_group_activation": "Group activation", + "telegram_allowed_user_ids": "Allowed user IDs", + "telegram_allowed_chat_ids": "Allowed chat IDs", + "telegram_allow_unaddressed_commands": "Allow commands without bot suffix", + "telegram_topic_isolation": "Isolate topic sessions", + "telegram_reply_to_message": "Quote source message", + "telegram_edited_messages": "Process edited messages", + "telegram_streaming_mode": "Telegram streaming mode", + "telegram_status_reactions": "Status reactions", + "telegram_disable_notification": "Silent delivery", + "telegram_protect_content": "Protect sent content", + "telegram_link_preview": "Link previews", + "telegram_command_menu": "Register command menu", + "telegram_albums": "Aggregate albums", + "telegram_audio_as_voice": "Send audio as voice", + "telegram_group_activationHelp": "Defaults match Gateway: all group messages and unaddressed commands are accepted. Choose mentions or replies to restrict activation. Telegram privacy mode also controls which updates reach the bot.", + "telegram_topic_isolationHelp": "Changing isolation starts separate sessions; existing history stays in its original session.", + "telegramSetupHelp": "These options require a compatible Gateway build; unsupported options are rejected when saving. Single-choice questions and /models offer native buttons, with pagination for model lists. Multi-select answers use text. Agent switching is not supported; configure a separate channel for each agent.", + "telegramInvalidChatIds": "Enter integer chat IDs separated by commas or whitespace; negative group IDs are supported.", + "telegram_option_always": "All messages", + "telegram_option_mention": "Mentions only", + "telegram_option_mention_or_reply": "Mentions or replies", + "telegram_option_off": "Off", + "telegram_option_auto": "Automatic", + "telegram_option_edit": "Edit message", + "telegram_option_draft": "Private chat draft", "label_telegram": "Telegram", "intro_agentchat": "Connect via the AgentChat protocol for internal debugging — no external credentials required.", "loading": "Loading channels...", diff --git a/dashboard/src/locales/zh.json b/dashboard/src/locales/zh.json index 2f5e297f65..17a08a6856 100644 --- a/dashboard/src/locales/zh.json +++ b/dashboard/src/locales/zh.json @@ -146,6 +146,7 @@ "STORAGE_BROWSE_FAILED": "无法浏览此存储后端。", "CHANNEL_KIND_UNSUPPORTED": "不支持的通道类型。", "CHANNEL_INVALID_CREDENTIALS": "通道凭证无效。", + "CHANNEL_OPTIONS_UNSUPPORTED": "当前安装的 octop-gateway 不支持这些 Telegram 选项。请先安装兼容的 Gateway 构建再保存。", "CHANNEL_NAME_TAKEN": "该通道名称已被使用,请换一个名称。", "CONNECTOR_NOT_FOUND": "未找到连接器。", "CONNECTOR_NAME_TAKEN": "该连接器名称已被使用,请换一个名称。", @@ -2536,6 +2537,32 @@ "label_agentchat": "AgentChat", "label_xiaoyi": "小艺", "label_mqtt": "MQTT", + "telegram_group_activation": "群聊触发方式", + "telegram_allowed_user_ids": "允许的用户 ID", + "telegram_allowed_chat_ids": "允许的聊天 ID", + "telegram_allow_unaddressed_commands": "允许无机器人后缀的命令", + "telegram_topic_isolation": "按话题隔离会话", + "telegram_reply_to_message": "引用原消息回复", + "telegram_edited_messages": "处理编辑后的消息", + "telegram_streaming_mode": "Telegram 流式模式", + "telegram_status_reactions": "状态表情回应", + "telegram_disable_notification": "静默发送", + "telegram_protect_content": "保护发送内容", + "telegram_link_preview": "链接预览", + "telegram_command_menu": "注册命令菜单", + "telegram_albums": "聚合相册", + "telegram_audio_as_voice": "将音频作为语音发送", + "telegram_group_activationHelp": "默认值与 Gateway 一致:接收所有群消息和未指定机器人的命令。可选择提及或回复以限制触发。Telegram 隐私模式也会影响机器人能收到的消息。", + "telegram_topic_isolationHelp": "切换隔离方式会使用独立会话,已有历史保留在原会话。", + "telegramSetupHelp": "这些选项需要兼容的 Gateway 版本,保存时会拒绝不支持的选项。单选问题和 /models 支持原生按钮,模型列表支持分页。多选问题使用文字回答。不支持切换 Agent;请为每个 Agent 配置独立渠道。", + "telegramInvalidChatIds": "请输入以逗号或空白分隔的整数聊天 ID,支持负数群 ID。", + "telegram_option_always": "所有消息", + "telegram_option_mention": "仅 @", + "telegram_option_mention_or_reply": "@ 或回复", + "telegram_option_off": "关闭", + "telegram_option_auto": "自动", + "telegram_option_edit": "编辑消息", + "telegram_option_draft": "私聊草稿", "label_telegram": "Telegram", "intro_agentchat": "通过 AgentChat 协议接入专家,适合内部联调,无需外部凭据。", "loading": "正在加载频道...", diff --git a/dashboard/src/pages/Agent/Channels/ChannelsPanel.test.tsx b/dashboard/src/pages/Agent/Channels/ChannelsPanel.test.tsx index 9a3795765f..5a3afaed1c 100644 --- a/dashboard/src/pages/Agent/Channels/ChannelsPanel.test.tsx +++ b/dashboard/src/pages/Agent/Channels/ChannelsPanel.test.tsx @@ -253,12 +253,30 @@ describe(" create-flow default", () => { expect(JSON.parse(String(init.body))).toEqual({ kind: "telegram", name: "telegram", - config: expect.objectContaining({ bot_token: "123456:ABC-token" }), + config: expect.objectContaining({ + bot_token: "123456:ABC-token", + group_activation: "always", + topic_isolation: false, + edited_messages: false, + streaming_mode: "off", + allow_unaddressed_commands: true, + reply_to_message: true, + status_reactions: false, + disable_notification: false, + protect_content: false, + link_preview: true, + command_menu: false, + albums: false, + audio_as_voice: false, + }), }); }); it("saves Telegram allowed user IDs as a deduplicated list", async () => { await openTelegramCreateDrawer(); + expect( + screen.getByText("channels.telegramAllowedUsersHelp"), + ).toBeInTheDocument(); await userEvent.type( await screen.findByLabelText(/Bot Token/i), @@ -307,3 +325,48 @@ describe(" create-flow default", () => { }); }); }); + +it.each([undefined, false, true])( + "preserves Telegram legacy activation and boolean %s on edit", + async (enabled) => { + const row = { id: "t1", kind: "telegram", name: "telegram", enabled: true }; + api.mockImplementation(async (url, init) => { + if (init?.method === "PATCH") return row; + if (url.endsWith("/t1")) + return { + ...row, + config: { + bot_token: "fake", + allowed_chat_ids: ["-100123"], + allowed_user_ids: ["42"], + ...(enabled === undefined + ? {} + : { topic_isolation: enabled, edited_messages: enabled }), + }, + }; + return [row]; + }); + render(); + await userEvent.click( + (await screen.findAllByText("channels.label_telegram"))[0], + ); + expect( + await screen.findByLabelText("channels.telegram_topic_isolation"), + ).toHaveAttribute("aria-checked", String(enabled ?? false)); + expect( + screen.getByLabelText("channels.telegram_allowed_chat_ids"), + ).toHaveValue("-100123"); + await userEvent.click(screen.getByRole("button", { name: "common.save" })); + await waitFor(() => { + const patch = api.mock.calls.find(([, init]) => init?.method === "PATCH"); + expect(patch).toBeDefined(); + expect(JSON.parse(String(patch![1]!.body)).config).toMatchObject({ + group_activation: "always", + topic_isolation: enabled ?? false, + edited_messages: enabled ?? false, + allowed_chat_ids: ["-100123"], + allowed_user_ids: ["42"], + }); + }); + }, +); diff --git a/dashboard/src/pages/Agent/Channels/ChannelsPanel.tsx b/dashboard/src/pages/Agent/Channels/ChannelsPanel.tsx index 3b0ddfd04c..e0e8fcb470 100644 --- a/dashboard/src/pages/Agent/Channels/ChannelsPanel.tsx +++ b/dashboard/src/pages/Agent/Channels/ChannelsPanel.tsx @@ -229,12 +229,21 @@ export default function ChannelsPanel({ agentId }: ChannelsPanelProps) { } if ( (row.kind === "discord" || row.kind === "telegram") && - (k === "allowed_channel_ids" || k === "allowed_user_ids") && + (k === "allowed_channel_ids" || + k === "allowed_user_ids" || + k === "allowed_chat_ids") && Array.isArray(v) ) { formCfg[k] = v.join("\n"); } else if (row.kind === "qq" && k === "group_context") { formCfg[k] = normalizeQqGroupContextConfig(v); + } else if ( + typeof v === "boolean" && + CHANNEL_FIELDS[row.kind as ChannelKey]?.some( + (f) => f.name === k && f.type === "switch", + ) + ) { + formCfg[k] = v; } else if (typeof v === "string") formCfg[k] = v; else if (typeof v === "number" || typeof v === "boolean") formCfg[k] = String(v); diff --git a/dashboard/src/pages/Agent/Channels/components/ChannelDrawer.tsx b/dashboard/src/pages/Agent/Channels/components/ChannelDrawer.tsx index 2d5aad102b..dcc7266290 100644 --- a/dashboard/src/pages/Agent/Channels/components/ChannelDrawer.tsx +++ b/dashboard/src/pages/Agent/Channels/components/ChannelDrawer.tsx @@ -163,19 +163,40 @@ interface ChannelDrawerProps { function FormItemForField({ field, disabled = false, + editing = false, }: { field: ChannelField; + editing?: boolean; disabled?: boolean; }) { const { t } = useTranslation(); const label = field.label.startsWith("channels.") ? t(field.label) : field.label; + const initialValue = editing ? field.legacyDefaultValue : field.defaultValue; + if (field.type === "select") { + return ( + + { + setRerankProviderId(id); + setRerankModel(undefined); + }} + placeholder={t("knowledgeBases.selectProvider")} + options={rerankProviders.map((provider) => ({ + value: provider.provider_id, + label: provider.provider_name, + }))} + notFoundContent={t("knowledgeBases.rerankNoProviders")} + /> + ({ + label: t(group.labelKey), + options: group.types.map((type) => { + const text = backendPolicyTypeLabel(type, t); + return { + value: type, + text, + label: , + }; + }), + }))} + placeholder={t("adminUsers.policyAllowedBackendTypesRequired")} + /> + + ) : null + } + 0, + allowed_backend_types: row.allowed_backend_types?.length + ? [...row.allowed_backend_types] + : undefined, }); }; @@ -2673,6 +2809,7 @@ export default function UsersListPanel() { limit_workspace_root: false, limit_token_quota: false, limit_max_agents: false, + limit_allowed_backend_types: false, create_default_expert: true, expert_template_id: DEFAULT_EXPERT_TEMPLATE_ID, }} diff --git a/dashboard/src/pages/Admin/Users/index.module.less b/dashboard/src/pages/Admin/Users/index.module.less index 133834b09e..cdd6c4f25c 100644 --- a/dashboard/src/pages/Admin/Users/index.module.less +++ b/dashboard/src/pages/Admin/Users/index.module.less @@ -93,6 +93,32 @@ margin-bottom: 12px !important; } +.backendTypeOption { + display: inline-flex; + align-items: center; + gap: 8px; + min-width: 0; + line-height: 1.4; +} + +.backendTypeIconSlot { + display: inline-flex; + align-items: center; + justify-content: center; + width: 18px; + height: 18px; + flex: none; + color: var(--fn-text-secondary); +} + +.backendTypeIcon { + width: 18px; + height: 18px; + border-radius: 4px; + object-fit: cover; + display: block; +} + .tokenQuotaField { display: flex; flex-direction: column; diff --git a/dashboard/src/pages/Experts/components/AgentBackendFields.tsx b/dashboard/src/pages/Experts/components/AgentBackendFields.tsx index fc98d9b6a2..5b3a2b0446 100644 --- a/dashboard/src/pages/Experts/components/AgentBackendFields.tsx +++ b/dashboard/src/pages/Experts/components/AgentBackendFields.tsx @@ -3,20 +3,28 @@ import { Form, Input, Select } from "antd"; import RootDirSelect from "./RootDirSelect"; import { MinusCircle } from "lucide-react"; import { useTranslation } from "react-i18next"; +import { useCurrentUser } from "../../../hooks/useCurrentUser"; import { BUILTIN_BACKENDS, DEFAULT_BACKEND, LEGACY_STATE_BACKEND, + defaultCreateBackendChoice, fetchFilesystemDefaults, joinWorkspaceDir, newWorkspaceAgentId, type BackendOption, type FilesystemDefaults, type PathMapping, + backendPolicyTypeLabel, builtinDesc, builtinLabel, + canonicalBackendPolicyType, + isBackendPolicyTypeAllowed, isHostRootDir, isValidCompositePath, + resolveCreateBackendChoice, + resolveRestrictedCompositeDefault, + restrictedBackendTypes, } from "./agentBackendForm"; import { HOST_FS_ROOT } from "./rootDirTree"; import styles from "../index.module.less"; @@ -52,8 +60,15 @@ export default function AgentBackendFields({ onRemovePathMapping, onUpdatePathMapping, }: AgentBackendFieldsProps) { - const { t } = useTranslation(); + const { t, i18n } = useTranslation(); const form = Form.useFormInstance(); + const allowedBackendTypes = useCurrentUser()?.allowed_backend_types; + const allowedSet = useMemo( + () => restrictedBackendTypes(allowedBackendTypes), + [allowedBackendTypes], + ); + const createDefaultChoice = defaultCreateBackendChoice(allowedBackendTypes); + const backendTouched = useRef(false); const [fsDefaults, setFsDefaults] = useState(null); const watchedRootDir = Form.useWatch("root_dir", form) as string | undefined; const watchedWorkspaceDir = Form.useWatch("workspace_dir", form) as @@ -129,70 +144,145 @@ export default function AgentBackendFields({ : [fsDefaults?.tree_root ?? HOST_FS_ROOT], [fsDefaults], ); - const legacyStateOption = useMemo( - () => ({ - value: LEGACY_STATE_BACKEND, - label: builtinLabel(LEGACY_STATE_BACKEND, t), - }), - [t], + const choiceLabel = (value: string): string => { + if (value === "composite") return t("experts.backendModes.composite"); + if ( + value === "local_shell" || + value === "filesystem" || + value === LEGACY_STATE_BACKEND + ) { + return builtinLabel(value, t); + } + if (value.startsWith("named:")) { + const name = value.slice("named:".length); + const row = backends.find((b) => b.name === name); + return row ? `${row.name} (${row.kind})` : value; + } + return value; + }; + const filteredBuiltins = useMemo( + () => + BUILTIN_BACKENDS.filter((mode) => + isBackendPolicyTypeAllowed(mode, allowedSet), + ), + [allowedSet], + ); + const filteredBackends = useMemo( + () => + backends.filter( + (b) => + b.enabled && + isBackendPolicyTypeAllowed(b.kind.toLowerCase(), allowedSet), + ), + [allowedSet, backends], + ); + const concreteValues = useMemo( + () => [ + ...filteredBuiltins, + ...filteredBackends.map((b) => `named:${b.name}`), + ], + [filteredBackends, filteredBuiltins], ); - const withLegacyState = ( + + useEffect(() => { + if (rootDirMode !== "create" || !allowedSet || disabled) return; + // The drawer reset writes ``local_shell`` in its own effect, after this + // one. Read the field on the next turn so that default does not stick. + const timer = window.setTimeout(() => { + const current = String(form.getFieldValue("backend_choice") ?? ""); + const next = resolveCreateBackendChoice(current, concreteValues, { + backendsLoading, + userTouched: backendTouched.current, + }); + if (next && next !== current) { + form.setFieldValue("backend_choice", next); + } + const currentDefault = String( + form.getFieldValue("composite_default") ?? "", + ); + const nextDefault = resolveRestrictedCompositeDefault( + currentDefault, + concreteValues, + backendsLoading, + ); + if (nextDefault === undefined) { + if (currentDefault) { + form.setFieldValue("composite_default", undefined); + } + } else if (nextDefault !== null && nextDefault !== currentDefault) { + form.setFieldValue("composite_default", nextDefault); + } + }, 0); + return () => window.clearTimeout(timer); + }, [ + allowedSet, + backendsLoading, + concreteValues, + disabled, + form, + rootDirMode, + ]); + + const retainSelected = ( options: { value: string; label: string }[], selected: string | undefined, - ) => - selected === LEGACY_STATE_BACKEND && - !options.some((option) => option.value === LEGACY_STATE_BACKEND) - ? [...options, legacyStateOption] - : options; + ) => { + if (!selected || options.some((option) => option.value === selected)) { + return options; + } + const keep = selected === LEGACY_STATE_BACKEND || rootDirMode === "edit"; + if (!keep) return options; + return [...options, { value: selected, label: choiceLabel(selected) }]; + }; const routeBackendOptions = useMemo(() => { - const builtins = BUILTIN_BACKENDS.map((mode) => ({ + const builtins = filteredBuiltins.map((mode) => ({ value: mode, label: builtinLabel(mode, t), })); - const configured = backends - .filter((b) => b.enabled) - .map((b) => ({ - value: `named:${b.name}` as const, - label: `${b.name} (${b.kind})`, - })); + const configured = filteredBackends.map((b) => ({ + value: `named:${b.name}` as const, + label: `${b.name} (${b.kind})`, + })); return [...builtins, ...configured]; - }, [backends, t]); + }, [filteredBackends, filteredBuiltins, t]); - const backendSelectOptions = useMemo( - () => [ + const backendSelectOptions = useMemo(() => { + const builtinOptions = retainSelected( + [ + ...filteredBuiltins.map((mode) => ({ + value: mode, + label: builtinLabel(mode, t), + })), + { + value: "composite", + label: t("experts.backendModes.composite"), + }, + ], + backendChoice.startsWith("named:") ? undefined : backendChoice, + ); + const configuredOptions = retainSelected( + filteredBackends.map((b) => ({ + value: `named:${b.name}`, + label: `${b.name} (${b.kind})`, + })), + backendChoice.startsWith("named:") ? backendChoice : undefined, + ); + return [ { label: t("experts.backendGroups.builtin"), - options: [ - ...BUILTIN_BACKENDS.map((mode) => ({ - value: mode, - label: builtinLabel(mode, t), - })), - ...(backendChoice === LEGACY_STATE_BACKEND - ? [legacyStateOption] - : []), - { - value: "composite", - label: t("experts.backendModes.composite"), - }, - ], + options: builtinOptions, }, - ...(backends.filter((b) => b.enabled).length > 0 + ...(configuredOptions.length > 0 ? [ { label: t("experts.backendGroups.configured"), - options: backends - .filter((b) => b.enabled) - .map((b) => ({ - value: `named:${b.name}`, - label: `${b.name} (${b.kind})`, - })), + options: configuredOptions, }, ] : []), - ], - [backendChoice, backends, legacyStateOption, t], - ); + ]; + }, [backendChoice, filteredBackends, filteredBuiltins, rootDirMode, t]); const desc = builtinDesc(backendChoice, t); const pathLocked = disabled || rootDirMode === "edit"; @@ -206,16 +296,42 @@ export default function AgentBackendFields({ onUpdatePathMapping(i, "backend", v)} style={{ flex: 1 }} diff --git a/dashboard/src/pages/Experts/components/CreateFromExpertDrawer.tsx b/dashboard/src/pages/Experts/components/CreateFromExpertDrawer.tsx index 25e4bc288e..a60988603e 100644 --- a/dashboard/src/pages/Experts/components/CreateFromExpertDrawer.tsx +++ b/dashboard/src/pages/Experts/components/CreateFromExpertDrawer.tsx @@ -47,6 +47,7 @@ import { type AgentRuntimeFormValues, } from "../../../utils/agentRuntimeConfig"; import { useAgentFormResources } from "../../../hooks/useAgentFormResources"; +import { useCurrentUser } from "../../../hooks/useCurrentUser"; import { pickLocale } from "../../../utils/localizedText"; import { buildModelSelectOptions, @@ -64,6 +65,7 @@ import { metaForFile } from "./iconForName"; import { buildBackendSpec, DEFAULT_BACKEND, + defaultCreateBackendChoice, ensureBubblewrapAfterProbe, ensureBwrapMessage, ensureBwrapToastKind, @@ -227,6 +229,8 @@ export default function CreateFromExpertDrawer({ onCreated, }: CreateFromExpertDrawerProps) { const { t } = useTranslation(); + const allowedBackendTypes = useCurrentUser()?.allowed_backend_types; + const createBackendChoice = defaultCreateBackendChoice(allowedBackendTypes); const [form] = Form.useForm< { name: string; @@ -335,7 +339,7 @@ export default function CreateFromExpertDrawer({ welcome_message: defaults.welcome_message, default_model: MODEL_AUTO_VALUE, conversation_mode: DEFAULT_CONVERSATION_MODE, - backend_choice: DEFAULT_BACKEND, + backend_choice: createBackendChoice, composite_default: DEFAULT_BACKEND, workspace_dir: "", workspace_dir_auto: "", @@ -390,7 +394,7 @@ export default function CreateFromExpertDrawer({ return () => { cancelled = true; }; - }, [open, source, sourceKey, lang, form]); + }, [open, source, sourceKey, lang, form, createBackendChoice]); useEffect(() => { if (!open) return; diff --git a/dashboard/src/pages/Experts/components/TeamDrawer.tsx b/dashboard/src/pages/Experts/components/TeamDrawer.tsx index 51f3bc7d0b..43036d8fb3 100644 --- a/dashboard/src/pages/Experts/components/TeamDrawer.tsx +++ b/dashboard/src/pages/Experts/components/TeamDrawer.tsx @@ -21,6 +21,7 @@ import { import { TextAssistBar } from "../../../components/TextAssistBar"; import type { OctopAgent } from "../../../context/AgentContext"; import { useAgentFormResources } from "../../../hooks/useAgentFormResources"; +import { useCurrentUser } from "../../../hooks/useCurrentUser"; import { apiErrorMessage } from "../../../utils/apiError"; import { buildModelSelectOptions, @@ -33,6 +34,7 @@ import ExpertAgentAvatar from "../../Chat/components/ExpertAgentAvatar"; import { buildBackendSpec, DEFAULT_BACKEND, + defaultCreateBackendChoice, ensureBubblewrapAfterProbe, ensureBwrapMessage, ensureBwrapToastKind, @@ -88,6 +90,8 @@ export default function TeamDrawer({ onIconUrlChange, }: TeamDrawerProps) { const { t } = useTranslation(); + const allowedBackendTypes = useCurrentUser()?.allowed_backend_types; + const createBackendChoice = defaultCreateBackendChoice(allowedBackendTypes); const [form] = Form.useForm(); const { models, modelsLoading, backends, backendsLoading } = useAgentFormResources(open); @@ -191,7 +195,7 @@ export default function TeamDrawer({ default_model: MODEL_AUTO_VALUE, welcome_message: t("experts.teams.welcomeDefault"), member_ids: [], - backend_choice: DEFAULT_BACKEND, + backend_choice: createBackendChoice, composite_default: DEFAULT_BACKEND, root_dir: undefined, workspace_dir: "", @@ -201,7 +205,7 @@ export default function TeamDrawer({ setIconUrl(TEAM_AVATAR_URL); setAvatarFile(null); setRosterExtras([]); - }, [form, mode, open, t, team]); + }, [createBackendChoice, form, mode, open, t, team]); useEffect(() => { if (!open) return; diff --git a/dashboard/src/pages/Experts/components/agentBackendForm.policy.test.ts b/dashboard/src/pages/Experts/components/agentBackendForm.policy.test.ts new file mode 100644 index 0000000000..f3ebb6d15e --- /dev/null +++ b/dashboard/src/pages/Experts/components/agentBackendForm.policy.test.ts @@ -0,0 +1,80 @@ +import { describe, expect, it } from "vitest"; +import { + defaultCreateBackendChoice, + resolveCreateBackendChoice, + resolveRestrictedCompositeDefault, +} from "./agentBackendForm"; + +describe("expert backend allow-list", () => { + it("keeps local_shell when the user is unrestricted or it is allowed", () => { + expect(defaultCreateBackendChoice(null)).toBe("local_shell"); + expect(defaultCreateBackendChoice(undefined)).toBe("local_shell"); + expect(defaultCreateBackendChoice([])).toBe("local_shell"); + expect(defaultCreateBackendChoice(["cos", "local_shell"])).toBe( + "local_shell", + ); + }); + + it("uses composite when local_shell is outside the allow-list", () => { + expect(defaultCreateBackendChoice(["cos", "s3"])).toBe("composite"); + }); + + it("replaces a disallowed local_shell and then prefers a loaded backend", () => { + expect( + resolveCreateBackendChoice("local_shell", [], { + backendsLoading: true, + userTouched: false, + }), + ).toBe("composite"); + expect( + resolveCreateBackendChoice("local_shell", ["named:assets"], { + backendsLoading: false, + userTouched: false, + }), + ).toBe("named:assets"); + expect( + resolveCreateBackendChoice("composite", ["named:assets"], { + backendsLoading: false, + userTouched: false, + }), + ).toBe("named:assets"); + }); + + it("leaves composite in place once the user has chosen it", () => { + expect( + resolveCreateBackendChoice("composite", ["named:assets"], { + backendsLoading: false, + userTouched: true, + }), + ).toBeNull(); + expect( + resolveCreateBackendChoice( + "named:assets", + ["named:assets", "named:logs"], + { + backendsLoading: false, + userTouched: true, + }, + ), + ).toBeNull(); + }); + + it("points the composite default at an allowed backend", () => { + expect( + resolveRestrictedCompositeDefault("local_shell", ["named:assets"], false), + ).toBe("named:assets"); + expect( + resolveRestrictedCompositeDefault( + "named:assets", + ["named:assets"], + false, + ), + ).toBeNull(); + expect( + resolveRestrictedCompositeDefault("local_shell", [], true), + ).toBeNull(); + expect( + resolveRestrictedCompositeDefault("local_shell", [], false), + ).toBeUndefined(); + }); +}); diff --git a/dashboard/src/pages/Experts/components/agentBackendForm.ts b/dashboard/src/pages/Experts/components/agentBackendForm.ts index 2e2d9920a4..827d07f1c2 100644 --- a/dashboard/src/pages/Experts/components/agentBackendForm.ts +++ b/dashboard/src/pages/Experts/components/agentBackendForm.ts @@ -1,12 +1,131 @@ import { request } from "../../../api/request"; export const BUILTIN_BACKENDS = ["local_shell", "filesystem"] as const; + +/** + * Types an admin can allow. ``composite`` is a wrapper: the expert form always + * offers it, and the allow-list only applies to the concrete backends inside. + */ +export const BACKEND_POLICY_TYPES = [ + "local_shell", + "filesystem", + "cos", + "s3", + "oss", + "obs", + "tos", + "custom", + "postgres", + "docker", + "opensandbox", +] as const; + +/** Storage kind ``shell`` is the same policy type as builtin ``local_shell``. */ +const BACKEND_POLICY_TYPE_ALIASES: Record = { + shell: "local_shell", +}; + +export function canonicalBackendPolicyType(type: string): string { + const token = type.toLowerCase(); + return BACKEND_POLICY_TYPE_ALIASES[token] ?? token; +} + +const BACKEND_POLICY_LABEL_KEYS: Record< + (typeof BACKEND_POLICY_TYPES)[number], + string +> = { + local_shell: "storage.kindShell", + filesystem: "storage.kindFilesystem", + cos: "storage.kindCos", + s3: "storage.kindS3", + oss: "storage.kindOss", + obs: "storage.kindObs", + tos: "storage.kindTos", + custom: "storage.kindCustom", + postgres: "storage.kindPostgres", + docker: "storage.kindDocker", + opensandbox: "storage.kindOpensandbox", +}; + +export function backendPolicyTypeLabel( + type: string, + t: (key: string) => string, +): string { + const key = + BACKEND_POLICY_LABEL_KEYS[type as (typeof BACKEND_POLICY_TYPES)[number]]; + return key ? t(key) : type; +} + +/** ``null`` means the user is not restricted. An empty list is also unrestricted. */ +export function restrictedBackendTypes( + allowed: readonly string[] | null | undefined, +): ReadonlySet | null { + if (!allowed || allowed.length === 0) return null; + return new Set(allowed.map((type) => canonicalBackendPolicyType(type))); +} + +export function isBackendPolicyTypeAllowed( + type: string, + allowed: ReadonlySet | null, +): boolean { + if (!allowed) return true; + return allowed.has(canonicalBackendPolicyType(type)); +} + /** Kept so an expert already saved as ``state`` still shows in the editor. */ export const LEGACY_STATE_BACKEND = "state"; export const DEFAULT_BACKEND: BuiltinBackend = "local_shell"; export type BuiltinBackend = (typeof BUILTIN_BACKENDS)[number]; export type BackendChoice = BuiltinBackend | "composite" | `named:${string}`; +/** Create-form default. ``composite`` stands in when ``local_shell`` is blocked. */ +export function defaultCreateBackendChoice( + allowed: readonly string[] | null | undefined, +): string { + const restricted = restrictedBackendTypes(allowed); + if (!restricted || isBackendPolicyTypeAllowed(DEFAULT_BACKEND, restricted)) { + return DEFAULT_BACKEND; + } + return "composite"; +} + +/** + * Replacement for a create-form backend choice that is outside the allow-list. + * ``null`` keeps the current value. ``composite`` is always legal. Until the + * user picks a value, the first allowed concrete backend replaces the + * placeholder once the storage list has loaded. + */ +export function resolveCreateBackendChoice( + current: string, + concreteValues: readonly string[], + options: { backendsLoading: boolean; userTouched: boolean }, +): string | null { + const concreteAllowed = concreteValues.includes(current); + if (options.userTouched && (concreteAllowed || current === "composite")) { + return null; + } + if (options.backendsLoading || concreteValues.length === 0) { + return current === "composite" ? null : "composite"; + } + const next = concreteValues[0]; + return current === next ? null : next; +} + +/** + * Composite child default under an allow-list. + * ``null`` keeps the field, ``undefined`` clears a disallowed value. + */ +export function resolveRestrictedCompositeDefault( + current: string, + concreteValues: readonly string[], + backendsLoading: boolean, +): string | null | undefined { + if (backendsLoading) return null; + if (concreteValues.includes(current)) return null; + if (concreteValues.length > 0) return concreteValues[0]; + return undefined; +} + export interface PathMapping { path: string; backend: string; diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000000..ec1db11ac0 --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,10 @@ +# Deployment + +[中文](README_CN.md) + +| Directory | Contents | +|-----------|----------| +| [docker/](docker/README.md) | Image build, Compose, and the container entrypoint | +| [k8s/](k8s/README.md) | Kubernetes: pgvector, multiple Octop replicas, one Ingress | + +`fnos/docker/` stays where it is. That tree is the FnOS package, not this image build. diff --git a/deploy/README_CN.md b/deploy/README_CN.md new file mode 100644 index 0000000000..4c0a374cbe --- /dev/null +++ b/deploy/README_CN.md @@ -0,0 +1,10 @@ +# 部署 + +[English](README.md) + +| 目录 | 内容 | +|------|------| +| [docker/](docker/README_CN.md) | 镜像构建、Compose、容器入口 | +| [k8s/](k8s/README_CN.md) | Kubernetes:pgvector、多个 Octop 副本、统一入口 | + +`fnos/docker/` 仍留在原处。那是飞牛安装包,不是这里的镜像构建目录。 diff --git a/docker/Dockerfile b/deploy/docker/Dockerfile similarity index 95% rename from docker/Dockerfile rename to deploy/docker/Dockerfile index a4aae85d7d..26e0ab2c55 100644 --- a/docker/Dockerfile +++ b/deploy/docker/Dockerfile @@ -6,22 +6,22 @@ # 阶段 2: Python 运行时 + 预构建前端 # # 用法(在仓库根目录执行,构建上下文为根目录): -# docker build -f docker/Dockerfile -t octop:latest . +# docker build -f deploy/docker/Dockerfile -t octop:latest . # docker run -d -p 8088:8088 --shm-size=1g -v octop-data:/data/.octop -e HOME=/data octop:latest # # --shm-size=1g 是启用远程桌面所必需的。Docker 默认 /dev/shm 只有 64MB,Xvnc 会起不来。 # compose 文件里已经写了 shm_size: 1gb。 # -# 国内加速(可选,需 BuildKit,docker/docker_build.sh 默认已开启): +# 国内加速(可选,需 BuildKit,deploy/docker/docker_build.sh 默认已开启): # PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \ # PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \ # NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \ # APT_MIRROR=mirrors.cloud.tencent.com \ -# bash docker/docker_build.sh +# bash deploy/docker/docker_build.sh # # 或直接传 build-arg: # docker build \ -# -f docker/Dockerfile \ +# -f deploy/docker/Dockerfile \ # --build-arg PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \ # --build-arg PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \ # --build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \ @@ -30,7 +30,7 @@ # -t octop:latest . # # 或使用 Compose: -# docker compose -f docker/docker-compose.yml up -d +# docker compose -f deploy/docker/docker-compose.yml up -d # # 默认 OCTOP_IMAGE_VARIANT=full:虚拟桌面、系统浏览器、本地向量和 OCR 都在镜像里, # 桌面不会启动,用户在控制台确认后才启用。桌面安装已经带上 Chromium,不再另下 @@ -150,8 +150,8 @@ COPY src/ ./src/ COPY --from=frontend-builder /build/src/octop/dashboard/ ./src/octop/dashboard/ COPY .env.example ./ -COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh -COPY docker/bake-desktop.sh /usr/local/bin/bake-desktop.sh +COPY deploy/docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh +COPY deploy/docker/bake-desktop.sh /usr/local/bin/bake-desktop.sh RUN chmod +x /usr/local/bin/docker-entrypoint.sh /usr/local/bin/bake-desktop.sh # pynput 在 import 时会连接 X。full 的无头构建只确认包已安装,不加载后端。 diff --git a/docker/README.md b/deploy/docker/README.md similarity index 86% rename from docker/README.md rename to deploy/docker/README.md index a75dc9f11e..2335048f6c 100644 --- a/docker/README.md +++ b/deploy/docker/README.md @@ -14,6 +14,7 @@ This directory contains the Docker build and deployment assets for Octop. | `docker-compose.yml` | One-command local / self-hosted deployment | | `docker-compose.cn.yml` | Same stack, pulls `ghcr.nju.edu.cn/tencentcloud/octop:latest` (no local build) | | `docker-compose.postgres.yml` | PostgreSQL (+ pgvector) for dual-backend dev/tests | +| `docker-compose.cluster.yml` | Lab: one PostgreSQL and two Octop processes with separate data directories | | `postgres/init-vector.sql` | Instance-level `CREATE EXTENSION vector` (initdb.d; **not** Octop migrations) | | `docker-entrypoint.sh` | Container entrypoint: first-run init + start server | @@ -24,7 +25,7 @@ This directory contains the Docker build and deployment assets for Octop. From the repository root: ```bash -docker compose -f docker/docker-compose.yml up -d --build +docker compose -f deploy/docker/docker-compose.yml up -d --build ``` Open `http://localhost:8088`. A valid `OCTOP_DEFAULT_PASSWORD` (≥8 characters with letters and digits) creates the admin on first boot and writes credentials to `/data/.octop/credential.txt`. If the variable is unset, or the password fails policy (too short, missing letters/digits, or a common password), **no** admin is created — open the dashboard and complete the setup wizard. The wizard unlock password is in `/data/.octop/octop-login.txt` (also noted in `credential.txt`). @@ -34,7 +35,7 @@ Compose sets the open-file limit to 65535 for multi-agent workloads. Server star **Option 2: Build script** ```bash -bash docker/docker_build.sh +bash deploy/docker/docker_build.sh docker run -d \ --name octop \ --ulimit nofile=65535:65535 \ @@ -55,7 +56,7 @@ PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \ PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \ NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \ APT_MIRROR=mirrors.cloud.tencent.com \ -bash docker/docker_build.sh +bash deploy/docker/docker_build.sh ``` ### Environment variables @@ -71,7 +72,7 @@ bash docker/docker_build.sh | `OPENAI_API_KEY` | — | OpenAI-compatible API key | | `DASHSCOPE_API_KEY` | — | Alibaba DashScope API key | -For Compose, put these in `docker/.env`. Values only reach the container if listed under `environment:` in `docker-compose.yml` (Compose interpolates `.env`; it does not auto-export every key). Alternatively write the same keys into the mounted data dir as `~/.octop/env`. +For Compose, put these in `deploy/docker/.env`. Values only reach the container if listed under `environment:` in `docker-compose.yml` (Compose interpolates `.env`; it does not auto-export every key). Alternatively write the same keys into the mounted data dir as `~/.octop/env`. ### Node.js @@ -97,6 +98,10 @@ image to receive these dependencies; restarting an older image is insufficient. - `docker run` example uses named volume `octop-data` - First boot: a valid `OCTOP_DEFAULT_PASSWORD` runs `octop init` and writes `credential.txt`; unset or rejected passwords skip admin creation and write the wizard unlock password to `/data/.octop/octop-login.txt`. The container does not exit because of a weak default. +### Kubernetes + +Manifests for multiple replicas, a shared PostgreSQL (with pgvector), and one external entrypoint are in [../k8s/README.md](../k8s/README.md). + ### Health check The image probes `GET /api/health`: @@ -110,6 +115,6 @@ curl http://localhost:8088/api/health ```bash docker logs -f octop docker exec -it octop octop --version -docker compose -f docker/docker-compose.yml down -docker compose -f docker/docker-compose.yml up -d --build +docker compose -f deploy/docker/docker-compose.yml down +docker compose -f deploy/docker/docker-compose.yml up -d --build ``` diff --git a/docker/README_CN.md b/deploy/docker/README_CN.md similarity index 86% rename from docker/README_CN.md rename to deploy/docker/README_CN.md index 626dc0deb8..5ef03325db 100644 --- a/docker/README_CN.md +++ b/deploy/docker/README_CN.md @@ -14,6 +14,7 @@ | `docker-compose.yml` | 本地开发 / 自托管一键启动 | | `docker-compose.cn.yml` | 同一套服务,拉取 `ghcr.nju.edu.cn/tencentcloud/octop:latest`(不本地构建) | | `docker-compose.postgres.yml` | 仅 PostgreSQL(+ pgvector)开发/测试库;扩展在 `postgres/init-vector.sql` | +| `docker-compose.cluster.yml` | 实验用:一台 PostgreSQL 加两个数据目录分开的 Octop | | `postgres/init-vector.sql` | 实例级 `CREATE EXTENSION vector`(initdb.d;**不**进 Octop 迁移) | | `docker-entrypoint.sh` | 容器入口:首次初始化数据库并启动服务 | @@ -24,7 +25,7 @@ 在仓库根目录执行: ```bash -docker compose -f docker/docker-compose.yml up -d --build +docker compose -f deploy/docker/docker-compose.yml up -d --build ``` 访问 `http://localhost:8088`。设置了合格的 `OCTOP_DEFAULT_PASSWORD`(≥8 位且同时包含字母和数字)时,首次启动会创建管理员,并把凭据写入 `/data/.octop/credential.txt`。未设置,或密码被策略拒绝(过短、缺字母/数字、常见弱密码)时,**不**自动建账号,打开页面走设置向导;向导口令在 `/data/.octop/octop-login.txt`(`credential.txt` 里也有说明)。在向导里自行设置管理员密码。 @@ -34,7 +35,7 @@ Compose 将多 agent 服务的文件描述符限制设为 65535。服务启动 **方式二:构建脚本** ```bash -bash docker/docker_build.sh +bash deploy/docker/docker_build.sh docker run -d \ --name octop \ --ulimit nofile=65535:65535 \ @@ -55,7 +56,7 @@ PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \ PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \ NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \ APT_MIRROR=mirrors.cloud.tencent.com \ -bash docker/docker_build.sh +bash deploy/docker/docker_build.sh ``` ### 常用环境变量 @@ -71,7 +72,7 @@ bash docker/docker_build.sh | `OPENAI_API_KEY` | — | OpenAI 兼容 API Key | | `DASHSCOPE_API_KEY` | — | 阿里云通义千问 API Key | -Compose 可在 `docker/.env` 中配置上述变量。注意:`.env` 只参与 Compose 插值,变量必须出现在 `docker-compose.yml` 的 `environment:` 中才会进入容器。也可把相同键写入挂载数据目录下的 `~/.octop/env`。 +Compose 可在 `deploy/docker/.env` 中配置上述变量。注意:`.env` 只参与 Compose 插值,变量必须出现在 `docker-compose.yml` 的 `environment:` 中才会进入容器。也可把相同键写入挂载数据目录下的 `~/.octop/env`。 ### Node.js @@ -94,6 +95,10 @@ Compose 可在 `docker/.env` 中配置上述变量。注意:`.env` 只参与 C - `docker run` 示例使用命名卷 `octop-data` - 首次启动:`OCTOP_DEFAULT_PASSWORD` 合格则执行 `octop init` 并写入 `credential.txt`;未设置或不合格则不建管理员,向导口令写入 `/data/.octop/octop-login.txt`,打开页面完成设置(容器不会因弱密码退出)。 +### Kubernetes + +多副本、共用 PostgreSQL(含 pgvector)和统一入口的清单在 [../k8s/README_CN.md](../k8s/README_CN.md)。 + ### 健康检查 镜像内置 `HEALTHCHECK`,探测 `GET /api/health`: @@ -107,6 +112,6 @@ curl http://localhost:8088/api/health ```bash docker logs -f octop docker exec -it octop octop --version -docker compose -f docker/docker-compose.yml down -docker compose -f docker/docker-compose.yml up -d --build +docker compose -f deploy/docker/docker-compose.yml down +docker compose -f deploy/docker/docker-compose.yml up -d --build ``` diff --git a/docker/bake-desktop.sh b/deploy/docker/bake-desktop.sh similarity index 100% rename from docker/bake-desktop.sh rename to deploy/docker/bake-desktop.sh diff --git a/deploy/docker/docker-compose.cluster.yml b/deploy/docker/docker-compose.cluster.yml new file mode 100644 index 0000000000..c1a679bd6e --- /dev/null +++ b/deploy/docker/docker-compose.cluster.yml @@ -0,0 +1,99 @@ +# ============================================================================= +# Lab: one PostgreSQL and two Octop processes with separate data directories. +# +# From the repository root: +# OCTOP_DEFAULT_PASSWORD='<8+ chars, letters and digits>' \ +# docker compose -f deploy/docker/docker-compose.cluster.yml up -d +# +# Host ports 8088 and 8089 both serve the same database. They are for checking +# that two processes share one control plane. Production traffic should enter +# through one sticky proxy (cookie affinity, long WebSocket timeout), not +# through these two ports directly. +# +# Do not mount one volume on both Octop services. Local workspace files and +# the Feishu dedup database are single-writer. +# ============================================================================= + +services: + octop-a: + image: ghcr.io/tencentcloud/octop:latest + restart: unless-stopped + ulimits: + nofile: + soft: 65535 + hard: 65535 + depends_on: + postgres: + condition: service_healthy + ports: + - "8088:8088" + volumes: + - octop_a:/data/.octop + environment: + - HOME=/data + - OCTOP_HOME=/data/.octop + - OCTOP_BIND_HOST=0.0.0.0 + - OCTOP_PORT=8088 + - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:?set an admin password of at least 8 characters with letters and digits} + - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin} + - OCTOP_DEFAULT_TIMEZONE=${OCTOP_DEFAULT_TIMEZONE:-Asia/Shanghai} + - OCTOP_CORS_ORIGINS=${OCTOP_CORS_ORIGINS:-} + - OCTOP_DATABASE_DRIVER=postgresql + - OCTOP_DATABASE_HOST=postgres + - OCTOP_DATABASE_PORT=5432 + - OCTOP_DATABASE_NAME=${OCTOP_PG_DB:-octop} + - OCTOP_DATABASE_USER=${OCTOP_PG_USER:-octop} + - OCTOP_DATABASE_PASSWORD=${OCTOP_PG_PASSWORD:-octop} + - OCTOP_DATABASE_URL=${OCTOP_DATABASE_URL:-} + + octop-b: + image: ghcr.io/tencentcloud/octop:latest + restart: unless-stopped + ulimits: + nofile: + soft: 65535 + hard: 65535 + depends_on: + postgres: + condition: service_healthy + ports: + - "8089:8088" + volumes: + - octop_b:/data/.octop + environment: + - HOME=/data + - OCTOP_HOME=/data/.octop + - OCTOP_BIND_HOST=0.0.0.0 + - OCTOP_PORT=8088 + - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:?set an admin password of at least 8 characters with letters and digits} + - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin} + - OCTOP_DEFAULT_TIMEZONE=${OCTOP_DEFAULT_TIMEZONE:-Asia/Shanghai} + - OCTOP_CORS_ORIGINS=${OCTOP_CORS_ORIGINS:-} + - OCTOP_DATABASE_DRIVER=postgresql + - OCTOP_DATABASE_HOST=postgres + - OCTOP_DATABASE_PORT=5432 + - OCTOP_DATABASE_NAME=${OCTOP_PG_DB:-octop} + - OCTOP_DATABASE_USER=${OCTOP_PG_USER:-octop} + - OCTOP_DATABASE_PASSWORD=${OCTOP_PG_PASSWORD:-octop} + - OCTOP_DATABASE_URL=${OCTOP_DATABASE_URL:-} + + postgres: + image: pgvector/pgvector:pg16 + restart: unless-stopped + environment: + POSTGRES_USER: ${OCTOP_PG_USER:-octop} + POSTGRES_PASSWORD: ${OCTOP_PG_PASSWORD:-octop} + POSTGRES_DB: ${OCTOP_PG_DB:-octop} + volumes: + - octop_pgdata:/var/lib/postgresql/data + - ./postgres/init-vector.sql:/docker-entrypoint-initdb.d/01-vector.sql:ro + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] + interval: 5s + timeout: 5s + retries: 10 + +volumes: + octop_a: + octop_b: + octop_pgdata: diff --git a/docker/docker-compose.cn.yml b/deploy/docker/docker-compose.cn.yml similarity index 74% rename from docker/docker-compose.cn.yml rename to deploy/docker/docker-compose.cn.yml index d6d564ede3..3822d54b5d 100644 --- a/docker/docker-compose.cn.yml +++ b/deploy/docker/docker-compose.cn.yml @@ -1,16 +1,18 @@ # ============================================================================= -# Octop — Docker Compose(国内镜像) +# Octop — Docker Compose (China image mirror) # -# 不在本地构建。官方 GHCR(ghcr.io/tencentcloud/octop)拉取失败时用本文件, -# 镜像来自南京大学 GHCR 源:ghcr.nju.edu.cn/tencentcloud/octop:latest +# Does not build locally. Use this when ghcr.io/tencentcloud/octop cannot be +# pulled. The image comes from the NJU GHCR mirror: +# ghcr.nju.edu.cn/tencentcloud/octop:latest # -# 用法(在仓库根目录执行): -# docker compose -f docker/docker-compose.cn.yml up -d -# OCTOP_PORT=9090 docker compose -f docker/docker-compose.cn.yml up -d -# OCTOP_DEFAULT_PASSWORD= docker compose -f docker/docker-compose.cn.yml up -d +# From the repository root: +# docker compose -f deploy/docker/docker-compose.cn.yml up -d +# OCTOP_PORT=9090 docker compose -f deploy/docker/docker-compose.cn.yml up -d +# OCTOP_DEFAULT_PASSWORD= docker compose -f deploy/docker/docker-compose.cn.yml up -d # -# 环境变量与 docker-compose.yml 相同。docker/.env 仅用于 Compose 插值; -# 变量必须列在下方 environment 才会进入容器。 +# Environment keys match docker-compose.yml. deploy/docker/.env is Compose +# interpolation only; a key enters the container only if listed under +# environment below. # ============================================================================= services: diff --git a/docker/docker-compose.mobile.yml b/deploy/docker/docker-compose.mobile.yml similarity index 93% rename from docker/docker-compose.mobile.yml rename to deploy/docker/docker-compose.mobile.yml index 62061398ff..42292aa92d 100644 --- a/docker/docker-compose.mobile.yml +++ b/deploy/docker/docker-compose.mobile.yml @@ -7,7 +7,7 @@ # https://dl.google.com/android/repository/platform-tools-latest-linux.zip \ # && unzip -qo pt.zip -d /workspace/Octop/.tools # -# docker compose -f docker/docker-compose.mobile.yml up -d --build +# docker compose -f deploy/docker/docker-compose.mobile.yml up -d --build # # This file is standalone (not an overlay) because ``network_mode: host`` # conflicts with published ``ports`` from the base compose file. @@ -21,8 +21,8 @@ services: octop: build: - context: .. - dockerfile: docker/Dockerfile + context: ../.. + dockerfile: deploy/docker/Dockerfile image: octop:latest container_name: octop restart: unless-stopped diff --git a/docker/docker-compose.postgres.yml b/deploy/docker/docker-compose.postgres.yml similarity index 90% rename from docker/docker-compose.postgres.yml rename to deploy/docker/docker-compose.postgres.yml index e2b1f242ee..4896cf1af8 100644 --- a/docker/docker-compose.postgres.yml +++ b/deploy/docker/docker-compose.postgres.yml @@ -2,8 +2,8 @@ # Local PostgreSQL (+ pgvector) for Octop dual-backend development / tests # # From repo root: -# docker compose -f docker/docker-compose.postgres.yml up -d -# docker compose -f docker/docker-compose.postgres.yml down +# docker compose -f deploy/docker/docker-compose.postgres.yml up -d +# docker compose -f deploy/docker/docker-compose.postgres.yml down # # Connection (default): # postgresql://octop:octop@127.0.0.1:5432/octop diff --git a/docker/docker-compose.yml b/deploy/docker/docker-compose.yml similarity index 73% rename from docker/docker-compose.yml rename to deploy/docker/docker-compose.yml index d23449f42c..439f8ccb6e 100644 --- a/docker/docker-compose.yml +++ b/deploy/docker/docker-compose.yml @@ -1,30 +1,31 @@ # ============================================================================= # Octop — Docker Compose # -# 用法(在仓库根目录执行): -# docker compose -f docker/docker-compose.yml up -d -# OCTOP_PORT=9090 docker compose -f docker/docker-compose.yml up -d -# OCTOP_DEFAULT_PASSWORD= docker compose -f docker/docker-compose.yml up -d +# From the repository root: +# docker compose -f deploy/docker/docker-compose.yml up -d +# OCTOP_PORT=9090 docker compose -f deploy/docker/docker-compose.yml up -d +# OCTOP_DEFAULT_PASSWORD= docker compose -f deploy/docker/docker-compose.yml up -d # -# 可在 docker/ 目录放置 .env 文件,例如: +# Optional deploy/docker/.env (Compose interpolation only), for example: # OCTOP_PORT=9090 # OCTOP_DEFAULT_PASSWORD= # OCTOP_ADMIN_USERNAME=admin # OCTOP_DATABASE_DRIVER=postgresql # OCTOP_DATABASE_URL=postgresql://octop:octop@host.docker.internal:5432/octop # -# 注意: docker/.env 仅用于 Compose 插值;变量必须列在下方 environment -# 才会进入容器。也可写入数据卷内的 ~/.octop/env(宿主机挂载目录下的 env)。 -# 密码须 ≥8 位且同时包含字母与数字(与控制台改密策略一致)。 -# 未设置或未通过策略时不自动建管理员,打开页面走设置向导 -# (向导口令写入 /data/.octop/octop-login.txt)。 +# A key in deploy/docker/.env reaches the container only when listed under +# environment below. The same keys can also live in ~/.octop/env on the +# mounted data directory. +# The password must be at least 8 characters and contain both letters and +# digits. If it is unset or rejected, no admin is created and the setup +# wizard starts (unlock password in /data/.octop/octop-login.txt). # ============================================================================= services: octop: build: - context: .. - dockerfile: docker/Dockerfile + context: ../.. + dockerfile: deploy/docker/Dockerfile image: octop:latest container_name: octop restart: unless-stopped diff --git a/docker/docker-entrypoint.sh b/deploy/docker/docker-entrypoint.sh similarity index 100% rename from docker/docker-entrypoint.sh rename to deploy/docker/docker-entrypoint.sh diff --git a/docker/docker_build.sh b/deploy/docker/docker_build.sh similarity index 81% rename from docker/docker_build.sh rename to deploy/docker/docker_build.sh index 2a0dc769fb..adf281d655 100644 --- a/docker/docker_build.sh +++ b/deploy/docker/docker_build.sh @@ -3,23 +3,23 @@ # 构建 Octop Docker 镜像 # # 用法: -# bash docker/docker_build.sh [镜像标签] [额外 docker build 参数...] +# bash deploy/docker/docker_build.sh [镜像标签] [额外 docker build 参数...] # # 示例: -# bash docker/docker_build.sh -# bash docker/docker_build.sh myreg/octop:v1 -# bash docker/docker_build.sh octop:dev --no-cache +# bash deploy/docker/docker_build.sh +# bash deploy/docker/docker_build.sh myreg/octop:v1 +# bash deploy/docker/docker_build.sh octop:dev --no-cache # # 国内加速(可选,需 BuildKit,本脚本默认已开启): # PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \ # PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \ # NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \ # APT_MIRROR=mirrors.cloud.tencent.com \ -# bash docker/docker_build.sh +# bash deploy/docker/docker_build.sh # ============================================================================= set -euo pipefail -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" cd "$REPO_ROOT" IMAGE_TAG="${1:-octop:latest}" @@ -53,7 +53,7 @@ echo "" docker build \ -t "$IMAGE_TAG" \ - -f "${REPO_ROOT}/docker/Dockerfile" \ + -f "${REPO_ROOT}/deploy/docker/Dockerfile" \ "${BUILD_ARGS[@]}" \ "$@" \ "$REPO_ROOT" @@ -65,4 +65,4 @@ echo "启动示例:" echo " docker run -d -p 8088:8088 -v octop-data:/data/.octop -e HOME=/data ${IMAGE_TAG}" echo "" echo "或使用 Compose:" -echo " docker compose -f docker/docker-compose.yml up -d" +echo " docker compose -f deploy/docker/docker-compose.yml up -d" diff --git a/docker/postgres/init-vector.sql b/deploy/docker/postgres/init-vector.sql similarity index 100% rename from docker/postgres/init-vector.sql rename to deploy/docker/postgres/init-vector.sql diff --git a/deploy/k8s/README.md b/deploy/k8s/README.md new file mode 100644 index 0000000000..e4b909bd11 --- /dev/null +++ b/deploy/k8s/README.md @@ -0,0 +1,114 @@ +# Octop on Kubernetes + +[中文](README_CN.md) + +One set of manifests deploys three things: PostgreSQL with pgvector, multiple Octop replicas, and one external entrypoint. The replicas share one control-plane configuration. Cron jobs and IM channels take a database lease so only one replica runs each of them. + +## What this stack shares + +The PostgreSQL control plane already holds the shared configuration: + +- Users, models, connectors, channels, and cron jobs +- Skill-package sources (`skill_package_files`) +- Knowledge-base originals and pgvector embeddings (`knowledge_files`, `knowledge_chunks`) +- The JWT secret (the `secrets` table; every replica reads the same row) +- Agent memory. With a PostgreSQL control plane, an agent that does not set its own memory backend uses that same database, in schema `agent_` + +A cron job or IM channel runs only after it claims a row lease. The lease lasts about 90 seconds and the holder renews it about every 30 seconds. Shutdown releases it. Another replica picks it up on the next reconcile. + +## What still depends on a sticky entrypoint + +Every replica loads the enabled experts at startup. The lease covers channels and cron runs, not the expert process. + +Dashboard WebSocket delivery and trajectory live updates stay in process memory. They are not forwarded across replicas. A chat request that lands on a different Pod drops the live stream. + +The Ingress cookie pins one browser to one Pod. After that Pod disappears, the next request moves to a live replica. Leave Service `sessionAffinity` unset. `ClientIP` affinity would pin every user who arrives through the same Ingress Pod to a single Octop replica. + +Agent workspace files follow that agent's backend. The default is the local filesystem on the Pod `emptyDir`, so those files disappear when the Pod is recreated. To keep them in a cluster, point the agent backend at S3, COS, OpenSandbox, or another movable backend. The Feishu dedup database is also local. After the Pod that held that channel is replaced, Feishu redelivery can be processed twice for a short time. + +## Requirements + +- Kubernetes and a default StorageClass (PostgreSQL requests a 20Gi ReadWriteOnce volume) +- Pull access to `pgvector/pgvector:pg16` and `ghcr.io/tencentcloud/octop:latest` +- Ingress NGINX. `ingressClassName` is `nginx`. Another controller needs its own class name and affinity annotations in `octop/ingress.yaml` +- A TLS certificate for `octop.example.com`, stored as Secret `octop-tls` + +`:latest` is the lite image. It has no virtual desktop, local embeddings, or OCR. For those, change the Deployment image to `ghcr.io/tencentcloud/octop:-full` and give the container about 1Gi of shm. + +## Files + +| File | Role | +|------|------| +| `kustomization.yaml` | Namespace `octop` and the resources below | +| `postgres/configmap.yaml` | `CREATE EXTENSION vector`, same SQL as `deploy/docker/postgres/init-vector.sql` | +| `postgres/` | Single-replica pgvector. The extension script runs only on first volume init | +| `octop/deployment.yaml` | Two replicas by default | +| `octop/service.yaml` | In-cluster `octop:8088`, no session affinity | +| `octop/ingress.yaml` | TLS, cookie stickiness, WebSocket timeouts, 100Mi uploads | +| `octop/pdb.yaml` | At most one replica down during voluntary disruption | +| `secrets.example.yaml` | Secret example, not part of the kustomization | + +## Install + +Run from the repository root. Database and admin passwords are separate secrets. The admin password must be at least 8 characters and contain both letters and digits. If it fails that policy, the entrypoint does not create an admin and each Pod starts the setup wizard on its own. + +```bash +kubectl apply -f deploy/k8s/namespace.yaml + +kubectl -n octop create secret generic octop-pg \ + --from-literal=user=octop \ + --from-literal=password="$(openssl rand -base64 24)" \ + --from-literal=database=octop + +kubectl -n octop create secret generic octop-admin \ + --from-literal=username=admin \ + --from-literal=password='REPLACE_WITH_ADMIN_PASSWORD' + +kubectl -n octop create secret tls octop-tls \ + --cert=fullchain.pem --key=privkey.pem + +kubectl apply -k deploy/k8s +kubectl -n octop rollout status statefulset/octop-pgvector +kubectl -n octop rollout status deploy/octop +``` + +On the first start both replicas may run `octop init`. The later one skips creation when the admin already exists and still starts. If the two inserts hit the unique constraint together, the later Pod exits once and skips creation after restart. That restart is expected. + +After the data volume is initialized, changing the username or password in `octop-pg` does not change the role already stored in Postgres. Change it with `ALTER USER`, then update the Secret. + +## Change the public hostname + +Change these together: + +1. `host` and `tls.hosts` in `octop/ingress.yaml` +2. `OCTOP_CORS_ORIGINS` in `octop/deployment.yaml` (include the scheme, for example `https://octop.example.com`) +3. TLS Secret `octop-tls` + +Apply again with `kubectl apply -k deploy/k8s`. + +## Check + +```bash +kubectl -n octop exec octop-pgvector-0 -- \ + sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "\dx"' + +kubectl -n octop port-forward svc/octop 8088:8088 +curl -fsS http://127.0.0.1:8088/api/health +``` + +`\dx` lists `vector`. `/api/health` returns JSON with `ok` true and `db` true. + +Open the Ingress host and sign in with the username and password from `octop-admin`. Channel and cron ownership shows up in the logs: the replica that claimed the lease runs the work, and the others record a skip. + +## Scale and roll + +```bash +kubectl -n octop scale deploy/octop --replicas=3 +kubectl -n octop rollout restart deploy/octop +``` + +A rolling update starts a new Pod before stopping an old one. The old Pod releases channel and cron leases on exit, and a new Pod claims them on the next reconcile. A page stuck to the old Pod disconnects; a refresh lands on a live replica. + +## Use a managed PostgreSQL + +Skip the `postgres/` manifests when the database is managed elsewhere. That server must already allow `CREATE EXTENSION vector` (many managed roles cannot create extensions themselves). Keep the Octop Deployment, Service, Ingress, and PDB, and point `OCTOP_DATABASE_HOST` at the managed address. Octop still applies control-plane migrations on startup. There is no need to run `*.pg.sql` by hand. diff --git a/deploy/k8s/README_CN.md b/deploy/k8s/README_CN.md new file mode 100644 index 0000000000..9dc11d009d --- /dev/null +++ b/deploy/k8s/README_CN.md @@ -0,0 +1,114 @@ +# Octop 集群部署(Kubernetes) + +[English](README.md) + +一套清单部署三样东西:带 pgvector 的 PostgreSQL、多个 Octop 副本、一个对外入口。副本共用同一套控制面配置。定时任务和 IM 通道用数据库租约保证只有一个副本在执行。 + +## 这套清单覆盖的范围 + +PostgreSQL 控制面里已经是全集群共享的: + +- 用户、模型、连接器、通道、定时任务 +- 技能包正文(`skill_package_files`) +- 知识库原文和 pgvector 向量(`knowledge_files`、`knowledge_chunks`) +- JWT 密钥(`secrets` 表,副本启动时读同一行) +- 专家记忆。控制面是 PostgreSQL 时,未单独指定的专家默认把记忆写到同一个库,按 `agent_` schema 分开 + +定时任务和 IM 通道在抢到行级租约后才运行。租约约 90 秒,持有副本大约每 30 秒续期;副本退出时会主动释放。别的副本在对账周期里接手。 + +## 还依赖入口粘滞的部分 + +每个副本启动时都会加载已启用的专家。租约限制的是通道和定时任务,不是专家进程。 + +Dashboard 的 WebSocket 和轨迹推送都在进程内存里,不跨副本转发。聊天请求如果换了一个 Pod,实时事件就断了。 + +因此 Ingress 用 cookie 把同一浏览器粘在同一个 Pod 上。Pod 消失后,下一次请求会换到存活副本。Service 保持不设置 `sessionAffinity: ClientIP`:流量若先经过同一个 Ingress Pod,ClientIP 会把所有用户粘到一个 Octop 副本。 + +专家工作区文件仍看该专家自己的 backend。默认是本机文件系统,落在 Pod 的 emptyDir 上,Pod 重建后这些文件不在了。集群里要保留工作区文件时,把专家 backend 配成 S3、COS、OpenSandbox 或其他可迁移后端。飞书通道的去重库也在本机;持有该通道的 Pod 被换掉后,可能短时间重复处理飞书补发的消息。 + +## 前置条件 + +- Kubernetes,以及默认 StorageClass(PostgreSQL 要 20Gi 的 ReadWriteOnce 卷) +- 能拉取 `pgvector/pgvector:pg16` 和 `ghcr.io/tencentcloud/octop:latest` +- Ingress NGINX。`ingressClassName` 是 `nginx`。别的入口控制器需要改 `octop/ingress.yaml` 里的类名和亲和注解 +- 一张给 `octop.example.com` 用的 TLS 证书,Secret 名字是 `octop-tls` + +`:latest` 是精简版,没有虚拟桌面、本地向量和 OCR。需要这些能力时把 Deployment 的镜像换成 `ghcr.io/tencentcloud/octop:-full`,并给容器加上大约 1Gi 的 `shm`。 + +## 文件 + +| 文件 | 作用 | +|------|------| +| `kustomization.yaml` | 命名空间 `octop`,汇总下面的资源 | +| `postgres/configmap.yaml` | `CREATE EXTENSION vector`,内容与 `deploy/docker/postgres/init-vector.sql` 一致 | +| `postgres/` | 单副本 pgvector。扩展只在数据卷第一次初始化时创建 | +| `octop/deployment.yaml` | 默认 2 个副本 | +| `octop/service.yaml` | 集群内 `octop:8088`,无会话亲和 | +| `octop/ingress.yaml` | TLS、cookie 粘滞、WebSocket 超时、100Mi 上传 | +| `octop/pdb.yaml` | 自愿中断时最多停 1 个副本 | +| `secrets.example.yaml` | Secret 样例,不在 kustomization 里 | + +## 部署 + +在仓库根目录执行。数据库口令和管理员口令分开。管理员口令至少 8 位,并且同时包含字母和数字;不合格时入口脚本不会建管理员,每个 Pod 会各自进入设置向导。 + +```bash +kubectl apply -f deploy/k8s/namespace.yaml + +kubectl -n octop create secret generic octop-pg \ + --from-literal=user=octop \ + --from-literal=password="$(openssl rand -base64 24)" \ + --from-literal=database=octop + +kubectl -n octop create secret generic octop-admin \ + --from-literal=username=admin \ + --from-literal=password='REPLACE_WITH_ADMIN_PASSWORD' + +kubectl -n octop create secret tls octop-tls \ + --cert=fullchain.pem --key=privkey.pem + +kubectl apply -k deploy/k8s +kubectl -n octop rollout status statefulset/octop-pgvector +kubectl -n octop rollout status deploy/octop +``` + +第一次启动时,两个副本可能同时执行 `octop init`。后完成的那个看到管理员已存在会跳过创建并继续启动。若两台正好撞上唯一约束,后一台退出并再启动一次,第二次跳过创建。这是预期行为。 + +库一旦初始化,再改 `octop-pg` 的用户名或密码不会改掉已有数据目录里的账号。要换口令,得进库执行 `ALTER USER`,再更新 Secret。 + +## 改入口域名 + +三处要一起改: + +1. `octop/ingress.yaml` 的 `host` 和 `tls.hosts` +2. `octop/deployment.yaml` 的 `OCTOP_CORS_ORIGINS`(带协议,例如 `https://octop.example.com`) +3. TLS Secret `octop-tls` + +然后重新 `kubectl apply -k deploy/k8s`。 + +## 验证 + +```bash +kubectl -n octop exec octop-pgvector-0 -- \ + sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "\dx"' + +kubectl -n octop port-forward svc/octop 8088:8088 +curl -fsS http://127.0.0.1:8088/api/health +``` + +`\dx` 里应能看到 `vector`。`/api/health` 返回 JSON,其中 `ok` 为 `true`,`db` 为 `true`。 + +浏览器打开 Ingress 域名,用 `octop-admin` 里的用户名和密码登录。通道和定时任务的运行身份可以在日志里确认:抢到租约的副本会执行,其他副本会记下跳过。 + +## 扩容和更新 + +```bash +kubectl -n octop scale deploy/octop --replicas=3 +kubectl -n octop rollout restart deploy/octop +``` + +滚动更新时先起新 Pod 再停旧 Pod。旧 Pod 退出时释放通道和任务租约,新 Pod 在对账周期内接手。已经粘在旧 Pod 上的页面会断开,刷新后进入存活副本。 + +## 换成托管 PostgreSQL + +可以不部署 `postgres/`。托管库需要预先允许 `CREATE EXTENSION vector`(很多托管角色不能自己建扩展)。然后只保留 Octop 的 Deployment、Service、Ingress、PDB,并把 `OCTOP_DATABASE_HOST` 指到托管地址。控制面迁移仍由 Octop 启动时执行,不需要手工跑 `*.pg.sql`。 diff --git a/deploy/k8s/kustomization.yaml b/deploy/k8s/kustomization.yaml new file mode 100644 index 0000000000..e6e1efdb35 --- /dev/null +++ b/deploy/k8s/kustomization.yaml @@ -0,0 +1,12 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +namespace: octop +resources: + - namespace.yaml + - postgres/configmap.yaml + - postgres/service.yaml + - postgres/statefulset.yaml + - octop/deployment.yaml + - octop/service.yaml + - octop/pdb.yaml + - octop/ingress.yaml diff --git a/deploy/k8s/namespace.yaml b/deploy/k8s/namespace.yaml new file mode 100644 index 0000000000..2843a3bdae --- /dev/null +++ b/deploy/k8s/namespace.yaml @@ -0,0 +1,6 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: octop + labels: + app.kubernetes.io/name: octop diff --git a/deploy/k8s/octop/deployment.yaml b/deploy/k8s/octop/deployment.yaml new file mode 100644 index 0000000000..306c8d4ebd --- /dev/null +++ b/deploy/k8s/octop/deployment.yaml @@ -0,0 +1,145 @@ +# Replicas share one PostgreSQL control plane. +# Browser sessions stick via the Ingress cookie. Do not add Service +# sessionAffinity: ClientIP, or every user behind one Ingress Pod lands +# on a single Octop replica. + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: octop + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server +spec: + replicas: 2 + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + selector: + matchLabels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server + template: + metadata: + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server + spec: + terminationGracePeriodSeconds: 60 + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server + topologyKey: kubernetes.io/hostname + initContainers: + - name: wait-for-postgres + image: pgvector/pgvector:pg16 + imagePullPolicy: IfNotPresent + command: + - sh + - -c + - until pg_isready -h octop-pgvector -p 5432; do sleep 2; done + containers: + - name: octop + # :latest is the lite image. Local embeddings, OCR, and the virtual + # desktop need :-full plus about 1Gi of shm. Desktop stays off. + + image: ghcr.io/tencentcloud/octop:latest + imagePullPolicy: IfNotPresent + ports: + - name: http + containerPort: 8088 + env: + - name: HOME + value: /data + - name: OCTOP_HOME + value: /data/.octop + - name: OCTOP_BIND_HOST + value: 0.0.0.0 + - name: OCTOP_PORT + value: "8088" + - name: OCTOP_DATABASE_DRIVER + value: postgresql + - name: OCTOP_DATABASE_HOST + value: octop-pgvector + - name: OCTOP_DATABASE_PORT + value: "5432" + - name: OCTOP_DATABASE_NAME + valueFrom: + secretKeyRef: + name: octop-pg + key: database + - name: OCTOP_DATABASE_USER + valueFrom: + secretKeyRef: + name: octop-pg + key: user + - name: OCTOP_DATABASE_PASSWORD + valueFrom: + secretKeyRef: + name: octop-pg + key: password + # The entrypoint reads OCTOP_DEFAULT_PASSWORD and runs octop init + # only when that password passes policy. + + - name: OCTOP_DEFAULT_PASSWORD + valueFrom: + secretKeyRef: + name: octop-admin + key: password + - name: OCTOP_ADMIN_USERNAME + valueFrom: + secretKeyRef: + name: octop-admin + key: username + - name: OCTOP_DEFAULT_TIMEZONE + value: Asia/Shanghai + # Keep this in sync with the Ingress host. + + - name: OCTOP_CORS_ORIGINS + value: https://octop.example.com + startupProbe: + httpGet: + path: /api/health + port: http + periodSeconds: 5 + failureThreshold: 36 + timeoutSeconds: 5 + readinessProbe: + httpGet: + path: /api/health + port: http + periodSeconds: 10 + timeoutSeconds: 5 + livenessProbe: + httpGet: + path: /api/health + port: http + periodSeconds: 30 + timeoutSeconds: 5 + failureThreshold: 3 + resources: + requests: + cpu: 500m + memory: 1Gi + limits: + cpu: "2" + memory: 4Gi + volumeMounts: + - name: home + mountPath: /data/.octop + volumes: + # Per-Pod runtime directory. Control plane, skill packages, and + # knowledge bases live in PostgreSQL. Do not switch this to + # ReadWriteMany: local SQLite such as the Feishu dedup file is not + # safe for concurrent writers. + + - name: home + emptyDir: {} diff --git a/deploy/k8s/octop/ingress.yaml b/deploy/k8s/octop/ingress.yaml new file mode 100644 index 0000000000..e12578dd82 --- /dev/null +++ b/deploy/k8s/octop/ingress.yaml @@ -0,0 +1,39 @@ +# Public entry. The cookie pins one browser's HTTP and WebSocket to one Pod. +# session-cookie-change-on-failure moves the next request after that Pod is gone. + +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: octop + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server + annotations: + nginx.ingress.kubernetes.io/affinity: cookie + nginx.ingress.kubernetes.io/affinity-mode: persistent + nginx.ingress.kubernetes.io/session-cookie-name: OCTOP_AFFINITY + nginx.ingress.kubernetes.io/session-cookie-secure: "true" + nginx.ingress.kubernetes.io/session-cookie-samesite: Lax + nginx.ingress.kubernetes.io/session-cookie-expires: "10800" + nginx.ingress.kubernetes.io/session-cookie-max-age: "10800" + nginx.ingress.kubernetes.io/session-cookie-change-on-failure: "true" + nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" + nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" + nginx.ingress.kubernetes.io/proxy-body-size: "100m" +spec: + ingressClassName: nginx + tls: + - hosts: + - octop.example.com + secretName: octop-tls + rules: + - host: octop.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: octop + port: + number: 8088 diff --git a/deploy/k8s/octop/pdb.yaml b/deploy/k8s/octop/pdb.yaml new file mode 100644 index 0000000000..e255c2edb6 --- /dev/null +++ b/deploy/k8s/octop/pdb.yaml @@ -0,0 +1,13 @@ +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: octop + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server +spec: + maxUnavailable: 1 + selector: + matchLabels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server diff --git a/deploy/k8s/octop/service.yaml b/deploy/k8s/octop/service.yaml new file mode 100644 index 0000000000..e404731e89 --- /dev/null +++ b/deploy/k8s/octop/service.yaml @@ -0,0 +1,16 @@ +apiVersion: v1 +kind: Service +metadata: + name: octop + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server +spec: + type: ClusterIP + selector: + app.kubernetes.io/name: octop + app.kubernetes.io/component: server + ports: + - name: http + port: 8088 + targetPort: http diff --git a/deploy/k8s/postgres/configmap.yaml b/deploy/k8s/postgres/configmap.yaml new file mode 100644 index 0000000000..1c8fc0918c --- /dev/null +++ b/deploy/k8s/postgres/configmap.yaml @@ -0,0 +1,17 @@ +# Keep in sync with deploy/docker/postgres/init-vector.sql. +# The script runs only when the data volume is initialized. + +apiVersion: v1 +kind: ConfigMap +metadata: + name: octop-pgvector-init + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: postgres +data: + init-vector.sql: | + -- Instance-level init only (docker-entrypoint-initdb.d on first volume). + -- NOT part of Octop control-plane migrations (see ADR 002). + -- Optional for local/dev pgvector image; control plane does not require it. + -- Managed Postgres: enable via your provider / DBA if embeddings need pgvector. + CREATE EXTENSION IF NOT EXISTS vector; diff --git a/deploy/k8s/postgres/service.yaml b/deploy/k8s/postgres/service.yaml new file mode 100644 index 0000000000..79b05f27ff --- /dev/null +++ b/deploy/k8s/postgres/service.yaml @@ -0,0 +1,18 @@ +# Headless Service for the StatefulSet. Clients use octop-pgvector:5432. + +apiVersion: v1 +kind: Service +metadata: + name: octop-pgvector + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: postgres +spec: + clusterIP: None + selector: + app.kubernetes.io/name: octop + app.kubernetes.io/component: postgres + ports: + - name: postgres + port: 5432 + targetPort: postgres diff --git a/deploy/k8s/postgres/statefulset.yaml b/deploy/k8s/postgres/statefulset.yaml new file mode 100644 index 0000000000..a6c2b5e288 --- /dev/null +++ b/deploy/k8s/postgres/statefulset.yaml @@ -0,0 +1,89 @@ +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: octop-pgvector + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: postgres +spec: + serviceName: octop-pgvector + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: postgres + template: + metadata: + labels: + app.kubernetes.io/name: octop + app.kubernetes.io/component: postgres + spec: + securityContext: + fsGroup: 999 + fsGroupChangePolicy: OnRootMismatch + containers: + - name: postgres + image: pgvector/pgvector:pg16 + imagePullPolicy: IfNotPresent + ports: + - name: postgres + containerPort: 5432 + env: + - name: POSTGRES_USER + valueFrom: + secretKeyRef: + name: octop-pg + key: user + - name: POSTGRES_PASSWORD + valueFrom: + secretKeyRef: + name: octop-pg + key: password + - name: POSTGRES_DB + valueFrom: + secretKeyRef: + name: octop-pg + key: database + volumeMounts: + - name: data + mountPath: /var/lib/postgresql/data + - name: initdb + mountPath: /docker-entrypoint-initdb.d + readOnly: true + readinessProbe: + exec: + command: + - sh + - -c + - pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" + initialDelaySeconds: 5 + periodSeconds: 5 + timeoutSeconds: 5 + livenessProbe: + exec: + command: + - sh + - -c + - pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" + initialDelaySeconds: 30 + periodSeconds: 20 + timeoutSeconds: 5 + resources: + requests: + cpu: 250m + memory: 512Mi + limits: + cpu: "2" + memory: 2Gi + volumes: + - name: initdb + configMap: + name: octop-pgvector-init + volumeClaimTemplates: + - metadata: + name: data + spec: + accessModes: ["ReadWriteOnce"] + resources: + requests: + storage: 20Gi diff --git a/deploy/k8s/secrets.example.yaml b/deploy/k8s/secrets.example.yaml new file mode 100644 index 0000000000..521106ee69 --- /dev/null +++ b/deploy/k8s/secrets.example.yaml @@ -0,0 +1,26 @@ +# Example only. Replace the passwords and apply this file on its own. +# Do not commit filled-in secrets. This file is not in kustomization.yaml. +# +# The admin password must be at least 8 characters and contain both letters +# and digits, and it must not be a common password. Otherwise the entrypoint +# does not create an admin and each Pod starts the setup wizard on its own. +apiVersion: v1 +kind: Secret +metadata: + name: octop-pg + namespace: octop +type: Opaque +stringData: + user: octop + password: REPLACE_WITH_DB_PASSWORD + database: octop +--- +apiVersion: v1 +kind: Secret +metadata: + name: octop-admin + namespace: octop +type: Opaque +stringData: + username: admin + password: REPLACE_WITH_ADMIN_PASSWORD diff --git a/desktop/README.md b/desktop/README.md index ba7d69be4a..d06b3d018a 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -55,7 +55,7 @@ CI can do it explicitly with `npx install-electron`. Node is pinned to **24** by `src/mise.toml`, overriding the repo-root pin of 20. That override is scoped to this directory and nowhere else: the Dashboard, -`docker/Dockerfile` (`node:20-slim`), `release.yml`, `fnos-build-fpk.yml`, +`deploy/docker/Dockerfile` (`node:20-slim`), `release.yml`, `fnos-build-fpk.yml`, `octop-desktop.yml` and the server all stay on Node 20. The reason for the split is `pnpm test`, which uses `node --test --experimental-strip-types` and needs Node ≥22.6 (on Node 20 the runner dies with `bad option`), plus Node 20's April diff --git a/docs/adr/002-database-backends.md b/docs/adr/002-database-backends.md index 75e961d1ea..ca5cd7dae7 100644 --- a/docs/adr/002-database-backends.md +++ b/docs/adr/002-database-backends.md @@ -53,7 +53,7 @@ Workspace content files (SOUL, skills, inbound, JSONL) remain files via `Backend |---------|--------|----------| | Control-plane tables / indexes | Octop migrate | `migrations/NNN_*.sql` and `NNN_*.pg.sql` | | Connection / session settings | Pool connect | SQLite: `PRAGMA` in `SqlitePool`; PG: defaults (FK on) — **not** in migrations | -| Instance extensions (`vector`, …) | Ops / docker | `docker/postgres/init-vector.sql` via `initdb.d`, or DBA on managed PG | +| Instance extensions (`vector`, …) | Ops / docker | `deploy/docker/postgres/init-vector.sql` via `initdb.d`, or DBA on managed PG | | Agent memory DDL | octop-memory | Runtime `_init_schema` per `agent_*` schema | **Hard rule:** Octop control-plane `*.pg.sql` must **not** run `CREATE EXTENSION`. Many managed Postgres roles cannot create extensions; the control plane also does not need `vector` (plain types only). octop-memory today uses built-in `tsvector`, not pgvector. Keep `CREATE EXTENSION vector` in docker/ops for optional future embedding use. diff --git a/docs/architecture.md b/docs/architecture.md index 60031ca7cd..52a84e1d5d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -166,3 +166,4 @@ checkpoint and are pushed to the dashboard / IM channel by [agent call](agent-call-agent.md), [agent delegation](agent-delegation.md) - [Agent backend file I/O](agent-backend-file-io.md) — content file rules +- [Deployment](../deploy/README.md) — Docker image/Compose and Kubernetes manifests diff --git a/docs/configuration.md b/docs/configuration.md index e88adb217e..69c339b24b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -214,8 +214,8 @@ remains in effect. `database_env_configured()` returns `True` when any `OCTOP_DATABASE_*` is set, which lets `OctopServer.start()` pick the configured backend at boot. -**Docker Compose:** put `OCTOP_DATABASE_*` in `docker/.env` *and* ensure -they are listed under `environment:` in `docker/docker-compose.yml` +**Docker Compose:** put `OCTOP_DATABASE_*` in `deploy/docker/.env` *and* ensure +they are listed under `environment:` in `deploy/docker/docker-compose.yml` (Compose uses `.env` for interpolation only; unset keys do not enter the container). Writing the same keys to the mounted `~/.octop/env` also works. @@ -225,7 +225,7 @@ originals are stored in that same database (`public.skill_package_files` and (`public.knowledge_chunks`). Names sit next to `skill_packages` and `knowledge_bases`. SQLite keeps the local `skill-packages/` and `knowledge/` directories. The `vector` extension is not created by Octop -migrations; enable it with `docker/postgres/init-vector.sql` or +migrations; enable it with `deploy/docker/postgres/init-vector.sql` or `CREATE EXTENSION vector` before indexing knowledge. There is no sqlite→PostgreSQL content migration in this release — pick the driver at install time. @@ -250,7 +250,7 @@ no automatic SQLite→PG memory data migration. PostgreSQL **extensions** (e.g. `vector`) are instance-level ops, not control-plane migrations. Local compose enables `vector` via -`docker/postgres/init-vector.sql`; managed databases need a DBA / +`deploy/docker/postgres/init-vector.sql`; managed databases need a DBA / provider toggle. See [ADR 002](./adr/002-database-backends.md). ### Scheduled SQLite checkpoint backups diff --git a/docs/user-guide.html b/docs/user-guide.html index f1517339ec..082bdd1546 100644 --- a/docs/user-guide.html +++ b/docs/user-guide.html @@ -223,10 +223,10 @@

2.3 验证安装

若提示 command not found: octop,请确认已重新加载 shell 或检查 ~/.octop/bin 是否在 PATH 中。

2.4 Docker 安装(生产推荐)

# 构建并后台启动
-docker compose -f docker/docker-compose.yml up -d
+docker compose -f deploy/docker/docker-compose.yml up -d
 
 # 或手动构建后运行
-bash docker/docker_build.sh
+bash deploy/docker/docker_build.sh
 docker run -d \
   -p 8088:8088 \
   -v octop-data:/data/.octop \
diff --git a/docs/user-guide.md b/docs/user-guide.md
index d0ff785339..421318e46f 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -112,10 +112,10 @@ octop run --help
 
 ```bash
 # 构建并后台启动
-docker compose -f docker/docker-compose.yml up -d
+docker compose -f deploy/docker/docker-compose.yml up -d
 
 # 或手动构建后运行
-bash docker/docker_build.sh
+bash deploy/docker/docker_build.sh
 docker run -d \
   -p 8088:8088 \
   -v octop-data:/data/.octop \
@@ -135,6 +135,8 @@ docker run -d \
 
 > 未设置或不合格的 `OCTOP_DEFAULT_PASSWORD` 不会静默换成随机管理员密码;打开页面走设置向导,向导口令在 `/data/.octop/octop-login.txt`。
 
+共用 PostgreSQL、多副本的 Kubernetes 部署见 [deploy/k8s/README_CN.md](../deploy/k8s/README_CN.md)。
+
 ---
 
 ## 三、首次启动与设置向导
diff --git a/fnos/docker/Dockerfile b/fnos/docker/Dockerfile
index 072226a2f7..32a82220d4 100644
--- a/fnos/docker/Dockerfile
+++ b/fnos/docker/Dockerfile
@@ -3,7 +3,7 @@
 # Octop — 可选的源码镜像(飞牛 FPK 不使用本文件)
 #
 # 飞牛 Docker 版安装包复用 docker-publish 推送的
-# ghcr.io/tencentcloud/octop:{version},那份镜像由 docker/Dockerfile 构建。
+# ghcr.io/tencentcloud/octop:{version},那份镜像由 deploy/docker/Dockerfile 构建。
 # 本文件只在显式执行下面的命令时使用,构建上下文为仓库根目录:
 #   docker build -f fnos/docker/Dockerfile -t octop:fnos-source .
 #
@@ -16,7 +16,7 @@
 # 另外用 bake-desktop.sh 装入虚拟桌面和系统 Chromium,但不启动。
 # 桌面组件已包含浏览器,不再另下 Playwright Chromium。
 # 运行时带 Node.js 20(node / npm / npx),供依赖 Node 的技能使用。
-# 飞牛 Docker 版安装包不构建本文件,而是拉取由 docker/Dockerfile 打出的镜像;
+# 飞牛 Docker 版安装包不构建本文件,而是拉取由 deploy/docker/Dockerfile 打出的镜像;
 # 两份 Dockerfile 的 Node 运行时保持一致。
 # Laya 不打进镜像:CPU 版 PyTorch 加多语言检查点大约要 4 GB 磁盘。
 #
@@ -101,8 +101,8 @@ COPY pyproject.toml README.md LICENSE ./
 COPY src/ ./src/
 COPY --from=frontend-builder /build/src/octop/dashboard/ ./src/octop/dashboard/
 
-COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
-COPY docker/bake-desktop.sh /usr/local/bin/bake-desktop.sh
+COPY deploy/docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+COPY deploy/docker/bake-desktop.sh /usr/local/bin/bake-desktop.sh
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh /usr/local/bin/bake-desktop.sh
 
 # 安装项目与附加组件。full 含桌面、本地向量和 OCR,由后面的 bake-desktop.sh 装入
diff --git a/mise.toml b/mise.toml
index 8879d7976f..216baa05bd 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,7 +1,7 @@
 # Local toolchain pins. Versions follow CI / Docker, not the host default.
 #
 # python 3.12  — CI matrix, Makefile `uv venv --python 3.12`
-# node 20      — docker/Dockerfile, release.yml, fnos-build-fpk.yml,
+# node 20      — deploy/docker/Dockerfile, release.yml, fnos-build-fpk.yml,
 #                 octop-desktop.yml, dashboard/ (its lockfile is npm 10)
 #                 desktop/src/ overrides this to Node 24 in its own
 #                 mise.toml — `node --test` type stripping needs >=22.6 there,
diff --git a/src/octop/api/routers/auth.py b/src/octop/api/routers/auth.py
index 61cc2d398a..8643081771 100644
--- a/src/octop/api/routers/auth.py
+++ b/src/octop/api/routers/auth.py
@@ -44,6 +44,7 @@ def me_payload(user: Any, server: Any) -> dict[str, Any]:
         payload["sso_kind"] = None
         payload["sso_identities"] = []
         payload["has_password"] = True
+        payload["allowed_backend_types"] = None
         return payload
     identities = [{"kind": item.kind} for item in server.user_manager.list_sso_identities(user.id)]
     payload["sso_identities"] = identities
@@ -58,6 +59,14 @@ def me_payload(user: Any, server: Any) -> dict[str, Any]:
         str(user.id),
         f"/api/users/{user.id}/avatar",
     )
+    from octop.infra.users.resource_policy import (  # noqa: PLC0415
+        POLICY_ALLOWED_BACKEND_TYPES,
+        allowed_backend_types_of,
+    )
+
+    payload["allowed_backend_types"] = allowed_backend_types_of(
+        server.services.user_policy_repo.get(user.id, POLICY_ALLOWED_BACKEND_TYPES)
+    )
     return payload
 
 
diff --git a/src/octop/api/routers/user_roles.py b/src/octop/api/routers/user_roles.py
index 45ebccc02b..20af2d3c0f 100644
--- a/src/octop/api/routers/user_roles.py
+++ b/src/octop/api/routers/user_roles.py
@@ -28,10 +28,13 @@
     validate_permission_keys,
 )
 from octop.infra.users.resource_policy import (
+    POLICY_ALLOWED_BACKEND_TYPES,
     POLICY_MAX_AGENTS,
     POLICY_TOKEN_QUOTA,
     POLICY_WORKSPACE_ROOT_DIR,
+    allowed_backend_types_of,
     max_agents_of,
+    normalize_allowed_backend_types,
     normalize_max_agents,
     normalize_token_quota,
     normalize_workspace_root_dir,
@@ -45,6 +48,7 @@
     POLICY_WORKSPACE_ROOT_DIR,
     POLICY_TOKEN_QUOTA,
     POLICY_MAX_AGENTS,
+    POLICY_ALLOWED_BACKEND_TYPES,
 }
 
 
@@ -135,6 +139,7 @@ def _policies_from_fields(
     workspace_root_dir: str | None,
     token_quota: int | None,
     max_agents: int | None,
+    allowed_backend_types: Any,
 ) -> list[tuple[str, str]]:
     items: list[tuple[str, str]] = []
     root = normalize_workspace_root_dir(workspace_root_dir)
@@ -146,6 +151,9 @@ def _policies_from_fields(
     agents = normalize_max_agents(max_agents)
     if agents is not None:
         items.append((POLICY_MAX_AGENTS, str(agents)))
+    backends = normalize_allowed_backend_types(allowed_backend_types)
+    if backends:
+        items.append((POLICY_ALLOWED_BACKEND_TYPES, backends))
     return items
 
 
@@ -162,6 +170,7 @@ def _policies_from_items(items: list[PolicyItem]) -> list[tuple[str, str]]:
         workspace_root_dir=by_name.get(POLICY_WORKSPACE_ROOT_DIR),
         token_quota=token_quota_of(by_name.get(POLICY_TOKEN_QUOTA)),
         max_agents=max_agents_of(by_name.get(POLICY_MAX_AGENTS)),
+        allowed_backend_types=by_name.get(POLICY_ALLOWED_BACKEND_TYPES),
     )
 
 
@@ -185,6 +194,7 @@ def public_role(row: UserRoleRow, *, avatar_url: str | None = None) -> dict[str,
         workspace_root_dir = None
         token_quota = None
         max_agents = None
+        allowed_backend_types = None
     else:
         permissions = expand_permission_grants(list(row.permissions))
         system_role = "user"
@@ -192,6 +202,9 @@ def public_role(row: UserRoleRow, *, avatar_url: str | None = None) -> dict[str,
         workspace_root_dir = workspace_root_dir_of(row.policy_value(POLICY_WORKSPACE_ROOT_DIR))
         token_quota = token_quota_of(row.policy_value(POLICY_TOKEN_QUOTA))
         max_agents = max_agents_of(row.policy_value(POLICY_MAX_AGENTS))
+        allowed_backend_types = allowed_backend_types_of(
+            row.policy_value(POLICY_ALLOWED_BACKEND_TYPES)
+        )
     return {
         "user_role_id": row.user_role_id,
         "user_role_name": row.user_role_name,
@@ -204,6 +217,7 @@ def public_role(row: UserRoleRow, *, avatar_url: str | None = None) -> dict[str,
         "workspace_root_dir": workspace_root_dir,
         "token_quota": token_quota,
         "max_agents": max_agents,
+        "allowed_backend_types": allowed_backend_types,
         "created_at": row.created_at,
         "updated_at": row.updated_at,
         "avatar_icon": row.avatar_icon,
diff --git a/src/octop/api/routers/users.py b/src/octop/api/routers/users.py
index 5ebf5aa149..57987c01d2 100644
--- a/src/octop/api/routers/users.py
+++ b/src/octop/api/routers/users.py
@@ -19,6 +19,7 @@
     expand_permission_grants,
 )
 from octop.infra.users.resource_policy import (
+    normalize_allowed_backend_types,
     normalize_max_agents,
     normalize_token_quota,
     normalize_workspace_root_dir,
@@ -53,6 +54,10 @@ class UserCreateBody(BaseModel):
     workspace_root_dir: str | None = None
     token_quota: int | None = Field(default=None, ge=0)
     max_agents: int | None = Field(default=None, ge=0)
+    allowed_backend_types: list[str] | None = Field(
+        default=None,
+        description="Backend types this user may select. null means unrestricted.",
+    )
     create_default_expert: bool = Field(
         default=False,
         description="When true, create one expert from expert_template_id in this request.",
@@ -78,6 +83,10 @@ class UserPatchBody(BaseModel):
     workspace_root_dir: str | None = None
     token_quota: int | None = Field(default=None, ge=0)
     max_agents: int | None = Field(default=None, ge=0)
+    allowed_backend_types: list[str] | None = Field(
+        default=None,
+        description="Backend types this user may select. null means unrestricted.",
+    )
 
 
 class ResetPasswordBody(BaseModel):
@@ -208,9 +217,11 @@ def _policy_kwargs_replace_from_pairs(pairs: list[tuple[str, str]]) -> dict[str,
     linger after a switch (including to admin, which has no resource limits).
     """
     from octop.infra.users.resource_policy import (
+        POLICY_ALLOWED_BACKEND_TYPES,
         POLICY_MAX_AGENTS,
         POLICY_TOKEN_QUOTA,
         POLICY_WORKSPACE_ROOT_DIR,
+        allowed_backend_types_of,
         max_agents_of,
         token_quota_of,
     )
@@ -220,6 +231,9 @@ def _policy_kwargs_replace_from_pairs(pairs: list[tuple[str, str]]) -> dict[str,
         "workspace_root_dir": by_name.get(POLICY_WORKSPACE_ROOT_DIR),
         "token_quota": token_quota_of(by_name.get(POLICY_TOKEN_QUOTA)),
         "max_agents": max_agents_of(by_name.get(POLICY_MAX_AGENTS)),
+        "allowed_backend_types": allowed_backend_types_of(
+            by_name.get(POLICY_ALLOWED_BACKEND_TYPES)
+        ),
     }
 
 
@@ -242,6 +256,8 @@ def _policy_kwargs_from_body(body: UserCreateBody | UserPatchBody) -> dict[str,
         policy_kwargs["token_quota"] = body.token_quota
     if "max_agents" in body.model_fields_set:
         policy_kwargs["max_agents"] = body.max_agents
+    if "allowed_backend_types" in body.model_fields_set:
+        policy_kwargs["allowed_backend_types"] = body.allowed_backend_types
     return policy_kwargs
 
 
@@ -368,6 +384,8 @@ async def create_user(
         normalize_token_quota(policy_kwargs["token_quota"])
     if "max_agents" in policy_kwargs:
         normalize_max_agents(policy_kwargs["max_agents"])
+    if "allowed_backend_types" in policy_kwargs:
+        normalize_allowed_backend_types(policy_kwargs["allowed_backend_types"])
     role_name = (
         _clean_role_name(body.role_name) if "role_name" in body.model_fields_set else template_name
     )
diff --git a/src/octop/i18n/en.json b/src/octop/i18n/en.json
index e03b191e98..5aa15c99f8 100644
--- a/src/octop/i18n/en.json
+++ b/src/octop/i18n/en.json
@@ -539,6 +539,7 @@
     "WORKSPACE_ROOT_CONTAINER_UNSUPPORTED": "Allowed storage root cannot be set while Octop is running in a container.",
     "TOKEN_QUOTA_EXCEEDED": "This account has reached its token quota. Please contact an administrator to raise the limit ({used}/{quota}).",
     "AGENT_QUOTA_EXCEEDED": "This account has reached its expert limit. Please contact an administrator to raise the limit ({used}/{quota}).",
+    "BACKEND_TYPE_NOT_ALLOWED": "This account cannot use backend type {types}.",
     "CAPTCHA_REQUIRED": "This server requires a captcha token to sign in.",
     "CAPTCHA_FAILED": "Captcha verification failed. Try again.",
     "CONFIG_FILE_CORRUPT": "Cannot update {path}: the file is not valid JSON ({detail}). Fix the syntax and retry — no settings were changed.",
diff --git a/src/octop/i18n/zh.json b/src/octop/i18n/zh.json
index 57d8848a0e..fef6e6751f 100644
--- a/src/octop/i18n/zh.json
+++ b/src/octop/i18n/zh.json
@@ -539,6 +539,7 @@
     "WORKSPACE_ROOT_CONTAINER_UNSUPPORTED": "容器环境下不能设置「允许的存储根目录」。",
     "TOKEN_QUOTA_EXCEEDED": "该账号已达到 token 配额上限,请联系管理员提升额度({used}/{quota})。",
     "AGENT_QUOTA_EXCEEDED": "该账号已达到专家数量上限,请联系管理员提升额度({used}/{quota})。",
+    "BACKEND_TYPE_NOT_ALLOWED": "该账号不能使用这些后端类型:{types}。",
     "CAPTCHA_REQUIRED": "此服务器登录需要验证码令牌。",
     "CAPTCHA_FAILED": "验证码校验失败,请重试。",
     "CONFIG_FILE_CORRUPT": "无法更新 {path}:该文件不是合法 JSON({detail})。请修正语法后重试;现有配置未被改动。",
diff --git a/src/octop/infra/agents/manager.py b/src/octop/infra/agents/manager.py
index bc25b693cd..9464630a82 100644
--- a/src/octop/infra/agents/manager.py
+++ b/src/octop/infra/agents/manager.py
@@ -848,6 +848,7 @@ async def create(
                 apply_workspace_root_to_config,
                 assert_agent_quota_available,
                 raise_if_backend_outside_user_root,
+                raise_if_backend_types_disallowed,
                 raise_if_workspace_dir_outside_user_root,
             )
 
@@ -876,6 +877,13 @@ async def create(
                     config,
                 )
                 self._assert_named_storage_backends(spec.user_id, config.get("backend"))
+                raise_if_backend_types_disallowed(
+                    self._repos.user_policy_repo,
+                    spec.user_id,
+                    config.get("backend"),
+                    named_kind=self._named_storage_kind,
+                    require_present=True,
+                )
                 self._assert_model_ref(spec.user_id, spec.default_model)
 
             # Create-time: user-assigned workspace_dir wins; otherwise default+encode.
@@ -1116,6 +1124,7 @@ async def update(self, agent_id: str, **kwargs: Any) -> AgentRow:
                     effective_workspace_root_dir,
                     persisted_workspace_within_root,
                     raise_if_backend_outside_user_root,
+                    raise_if_backend_types_disallowed,
                 )
 
                 allowed_root = effective_workspace_root_dir(
@@ -1141,6 +1150,13 @@ async def update(self, agent_id: str, **kwargs: Any) -> AgentRow:
                     owner_row.user_id,
                     parsed_profile_cfg.get("backend"),
                 )
+                raise_if_backend_types_disallowed(
+                    self._repos.user_policy_repo,
+                    owner_row.user_id,
+                    parsed_profile_cfg.get("backend"),
+                    named_kind=self._named_storage_kind,
+                    previous=parse_config_json(owner_row.config_json).get("backend"),
+                )
             lifted = extract_profile_from_config(parsed_profile_cfg)
             kwargs["config_json"] = dumps_config(parsed_profile_cfg)
             for key, value in lifted.items():
@@ -3216,6 +3232,13 @@ def _assert_model_ref(self, user_id: int, model_ref: str | None) -> None:
             is_owner=False,
         )
 
+    def _named_storage_kind(self, name: str) -> str | None:
+        row = self._repos.storage_backend_repo.get_by_name(name)
+        if row is None:
+            return None
+        kind = (row.kind or "").strip().lower()
+        return kind or None
+
     def _assert_named_storage_backends(self, user_id: int, backend: Any) -> None:
         from octop.infra.backend.resolver import collect_named_storage_backend_refs
         from octop.infra.users.groups import RESOURCE_STORAGE_BACKEND, GroupAccess
diff --git a/src/octop/infra/errors.py b/src/octop/infra/errors.py
index 633067cf22..9a9ef9784e 100644
--- a/src/octop/infra/errors.py
+++ b/src/octop/infra/errors.py
@@ -160,6 +160,7 @@ class ErrorCode(StrEnum):
     WORKSPACE_ROOT_CONTAINER_UNSUPPORTED = "WORKSPACE_ROOT_CONTAINER_UNSUPPORTED"
     TOKEN_QUOTA_EXCEEDED = "TOKEN_QUOTA_EXCEEDED"
     AGENT_QUOTA_EXCEEDED = "AGENT_QUOTA_EXCEEDED"
+    BACKEND_TYPE_NOT_ALLOWED = "BACKEND_TYPE_NOT_ALLOWED"
     CAPTCHA_REQUIRED = "CAPTCHA_REQUIRED"
     CAPTCHA_FAILED = "CAPTCHA_FAILED"
     MFA_INVALID = "MFA_INVALID"
@@ -330,6 +331,7 @@ class ErrorCode(StrEnum):
     ErrorCode.WORKSPACE_ROOT_CONTAINER_UNSUPPORTED: 400,
     ErrorCode.TOKEN_QUOTA_EXCEEDED: 403,
     ErrorCode.AGENT_QUOTA_EXCEEDED: 403,
+    ErrorCode.BACKEND_TYPE_NOT_ALLOWED: 403,
     ErrorCode.CAPTCHA_REQUIRED: 400,
     ErrorCode.CAPTCHA_FAILED: 400,
     ErrorCode.MFA_INVALID: 401,
diff --git a/src/octop/infra/knowledge/pg_index.py b/src/octop/infra/knowledge/pg_index.py
index 82d2dc4882..75d85862e9 100644
--- a/src/octop/infra/knowledge/pg_index.py
+++ b/src/octop/infra/knowledge/pg_index.py
@@ -1,7 +1,7 @@
 """pgvector chunk index for one knowledge base.
 
 ``CREATE EXTENSION vector`` is an operator step (see
-``docker/postgres/init-vector.sql`` and ADR 002). This module only creates
+``deploy/docker/postgres/init-vector.sql`` and ADR 002). This module only creates
 ``public.knowledge_chunks`` once the ``vector`` type exists.
 """
 
@@ -42,7 +42,7 @@ def _ensure_schema(self) -> None:
             if present is None:
                 raise RuntimeError(
                     "pgvector is not installed on this PostgreSQL. "
-                    "Run CREATE EXTENSION vector (docker/postgres/init-vector.sql) "
+                    "Run CREATE EXTENSION vector (deploy/docker/postgres/init-vector.sql) "
                     "before using knowledge search with database.driver=postgresql."
                 )
             adopt_legacy_content_tables(self._database)
diff --git a/src/octop/infra/users/manager.py b/src/octop/infra/users/manager.py
index a46351691f..7df80512d9 100644
--- a/src/octop/infra/users/manager.py
+++ b/src/octop/infra/users/manager.py
@@ -579,11 +579,14 @@ async def set_resource_policy(
         workspace_root_dir: Any = UNSET,
         token_quota: Any = UNSET,
         max_agents: Any = UNSET,
+        allowed_backend_types: Any = UNSET,
     ) -> None:
         from octop.infra.users.resource_policy import (
+            POLICY_ALLOWED_BACKEND_TYPES,
             POLICY_MAX_AGENTS,
             POLICY_TOKEN_QUOTA,
             POLICY_WORKSPACE_ROOT_DIR,
+            normalize_allowed_backend_types,
             normalize_max_agents,
             normalize_token_quota,
             normalize_workspace_root_dir,
@@ -596,6 +599,7 @@ async def set_resource_policy(
         root_arg: Any = UNSET
         quota_arg: Any = UNSET
         max_agents_arg: Any = UNSET
+        backend_types_arg: Any = UNSET
         if workspace_root_dir is not UNSET:
             root_arg = normalize_workspace_root_dir(workspace_root_dir)
             updates[POLICY_WORKSPACE_ROOT_DIR] = root_arg
@@ -605,6 +609,9 @@ async def set_resource_policy(
         if max_agents is not UNSET:
             max_agents_arg = normalize_max_agents(max_agents)
             updates[POLICY_MAX_AGENTS] = None if max_agents_arg is None else str(max_agents_arg)
+        if allowed_backend_types is not UNSET:
+            backend_types_arg = normalize_allowed_backend_types(allowed_backend_types)
+            updates[POLICY_ALLOWED_BACKEND_TYPES] = backend_types_arg
         if not updates:
             return
         self._services.user_policy_repo.merge(row.id, updates)
@@ -629,6 +636,13 @@ async def set_resource_policy(
                 target=username,
                 payload=str(max_agents_arg) if max_agents_arg is not None else "",
             )
+        if allowed_backend_types is not UNSET:
+            self._services.audit_repo.write(
+                actor=ACTOR_ADMIN,
+                action="user.set_allowed_backend_types",
+                target=username,
+                payload=backend_types_arg or "",
+            )
 
     async def set_workspace_root_dir(self, username: str, workspace_root_dir: str | None) -> None:
         await self.set_resource_policy(username, workspace_root_dir=workspace_root_dir)
diff --git a/src/octop/infra/users/resource_policy.py b/src/octop/infra/users/resource_policy.py
index 3b55273db7..634780c304 100644
--- a/src/octop/infra/users/resource_policy.py
+++ b/src/octop/infra/users/resource_policy.py
@@ -1,9 +1,10 @@
-"""Per-user named policies: workspace root, token quota, and future rows."""
+"""Per-user named policies: workspace root, token quota, backend types, and future rows."""
 
 from __future__ import annotations
 
+import json
 import os
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from typing import Any
 
 from octop.infra.errors import ErrorCode, OctopError
@@ -21,6 +22,26 @@
 POLICY_WORKSPACE_ROOT_DIR = "workspace_root_dir"
 POLICY_TOKEN_QUOTA = "token_quota"
 POLICY_MAX_AGENTS = "max_agents"
+POLICY_ALLOWED_BACKEND_TYPES = "allowed_backend_types"
+
+# Expert-picker types. Storage kind ``shell`` is the same capability as builtin
+# ``local_shell``. Builtin filesystem and storage kind ``filesystem`` share one
+# type. ``composite`` is a wrapper, not a policy value.
+BACKEND_POLICY_TYPES: tuple[str, ...] = (
+    "local_shell",
+    "filesystem",
+    "cos",
+    "s3",
+    "oss",
+    "obs",
+    "tos",
+    "custom",
+    "postgres",
+    "docker",
+    "opensandbox",
+)
+_BACKEND_POLICY_TYPE_SET = frozenset(BACKEND_POLICY_TYPES)
+_POLICY_TYPE_ALIASES = {"shell": "local_shell"}
 
 
 def active_policy_value(row: Any) -> str | None:
@@ -107,6 +128,9 @@ def public_policy_fields(rows: Sequence[Any] | Mapping[str, str] | None) -> dict
         "workspace_root_dir": workspace_root_dir_of(by_name),
         "token_quota": token_quota_of(by_name.get(POLICY_TOKEN_QUOTA)),
         "max_agents": max_agents_of(by_name.get(POLICY_MAX_AGENTS)),
+        "allowed_backend_types": allowed_backend_types_of(
+            by_name.get(POLICY_ALLOWED_BACKEND_TYPES)
+        ),
     }
 
 
@@ -160,6 +184,171 @@ def normalize_max_agents(raw: int | None) -> int | None:
     return limit
 
 
+def _backend_type_tokens(raw: Any) -> list[str]:
+    if raw is None:
+        return []
+    if isinstance(raw, str):
+        text = raw.strip()
+        if not text:
+            return []
+        if text.startswith("["):
+            try:
+                parsed = json.loads(text)
+            except json.JSONDecodeError as exc:
+                raise OctopError(
+                    ErrorCode.FORBIDDEN,
+                    "invalid backend type list",
+                    status=400,
+                ) from exc
+            raw = parsed
+        else:
+            raw = [part.strip() for part in text.split(",")]
+    if isinstance(raw, (list, tuple, set)):
+        tokens: list[str] = []
+        seen: set[str] = set()
+        for item in raw:
+            token = str(item).strip().lower()
+            if not token or token in seen:
+                continue
+            seen.add(token)
+            tokens.append(token)
+        return tokens
+    raise OctopError(ErrorCode.FORBIDDEN, "invalid backend type list", status=400)
+
+
+def _canonical_policy_type(token: str) -> str:
+    return _POLICY_TYPE_ALIASES.get(token, token)
+
+
+def normalize_allowed_backend_types(raw: Any) -> str | None:
+    """Return catalog-ordered types, or ``None`` when the user is unrestricted.
+
+    Empty input clears the policy. Unknown names are rejected. ``shell`` is
+    stored as ``local_shell``.
+    """
+    tokens = _backend_type_tokens(raw)
+    if not tokens:
+        return None
+    selected = {_canonical_policy_type(token) for token in tokens}
+    unknown = [
+        token for token in tokens if _canonical_policy_type(token) not in _BACKEND_POLICY_TYPE_SET
+    ]
+    if unknown:
+        raise OctopError(
+            ErrorCode.FORBIDDEN,
+            f"unknown backend types: {unknown}",
+            status=400,
+        )
+    return ",".join(token for token in BACKEND_POLICY_TYPES if token in selected)
+
+
+def allowed_backend_types_of(raw: Any) -> list[str] | None:
+    """Enabled allow-list, or ``None`` when this policy does not apply."""
+    if isinstance(raw, (list, tuple, set)):
+        stored = normalize_allowed_backend_types(raw)
+        return stored.split(",") if stored else None
+    if isinstance(raw, Mapping) and "value" not in raw and POLICY_ALLOWED_BACKEND_TYPES in raw:
+        raw = raw.get(POLICY_ALLOWED_BACKEND_TYPES)
+    text = active_policy_value(raw)
+    if text is None:
+        return None
+    selected = [
+        _canonical_policy_type(token)
+        for token in (part.strip().lower() for part in text.split(","))
+        if _canonical_policy_type(token) in _BACKEND_POLICY_TYPE_SET
+    ]
+    ordered = [token for token in BACKEND_POLICY_TYPES if token in selected]
+    return ordered or None
+
+
+def backend_policy_types_in(
+    spec: Any,
+    *,
+    named_kind: Callable[[str], str | None],
+) -> set[str]:
+    """Policy types referenced by an agent backend spec, including composites."""
+    found: set[str] = set()
+
+    def add_named(name: str) -> None:
+        kind = named_kind(name)
+        if kind:
+            found.add(_canonical_policy_type(kind.strip().lower()))
+
+    def walk(node: Any) -> None:
+        if node is None:
+            return
+        if isinstance(node, str):
+            text = node.strip()
+            if not text:
+                return
+            if text.startswith("named:"):
+                add_named(text.split(":", 1)[1])
+                return
+            found.add(_canonical_policy_type(text.lower()))
+            return
+        if not isinstance(node, dict):
+            return
+        kind = node.get("type")
+        if not isinstance(kind, str) or not kind.strip():
+            return
+        kind = kind.strip().lower()
+        if kind == "named":
+            name = node.get("name")
+            if isinstance(name, str) and name.strip():
+                add_named(name.strip())
+            return
+        if kind == "composite":
+            walk(node.get("default"))
+            routes = node.get("routes")
+            if isinstance(routes, dict):
+                for sub in routes.values():
+                    walk(sub)
+            return
+        found.add(_canonical_policy_type(kind))
+
+    walk(spec)
+    return found
+
+
+def raise_if_backend_types_disallowed(
+    policy_repo: Any,
+    user_id: int,
+    backend: Any,
+    *,
+    named_kind: Callable[[str], str | None],
+    previous: Any = None,
+    require_present: bool = False,
+) -> None:
+    """Reject backend types outside the user's allow-list.
+
+    A missing policy is unrestricted. On update, types already stored on the
+    agent stay valid so an unrelated edit can still save. A create that omits
+    the backend is treated as the default ``local_shell``.
+    """
+    allowed = allowed_backend_types_of(policy_repo.get(user_id, POLICY_ALLOWED_BACKEND_TYPES))
+    if not allowed:
+        return
+    allowed_set = set(allowed)
+    if backend in (None, {}) and require_present:
+        used = {"local_shell"}
+    else:
+        used = backend_policy_types_in(backend, named_kind=named_kind)
+    if previous is not None:
+        used -= backend_policy_types_in(previous, named_kind=named_kind)
+    blocked = [
+        token for token in BACKEND_POLICY_TYPES if token in used and token not in allowed_set
+    ]
+    blocked.extend(sorted(used - allowed_set - _BACKEND_POLICY_TYPE_SET))
+    if not blocked:
+        return
+    types = ", ".join(blocked)
+    raise OctopError(
+        ErrorCode.BACKEND_TYPE_NOT_ALLOWED,
+        f"backend types not allowed: {types}",
+        details={"types": types},
+    )
+
+
 def assert_backend_within_user_root(
     backend: Any,
     allowed_root: str | None,
diff --git a/tests/integration/test_user_roles_api.py b/tests/integration/test_user_roles_api.py
index 77e341a6d9..2be15041f0 100644
--- a/tests/integration/test_user_roles_api.py
+++ b/tests/integration/test_user_roles_api.py
@@ -405,3 +405,129 @@ async def test_create_user_keeps_user_when_expert_template_missing(env):
     agents = await c.get("/api/agents", headers=auth, params={"scope": "all"})
     owned = [row for row in agents.json() if row["user_id"] == created.json()["id"]]
     assert owned == []
+
+
+async def test_allowed_backend_types_limit_expert_create(env):
+    c, _srv, auth = env
+    created = await c.post(
+        "/api/users/roles",
+        headers=auth,
+        json={
+            "user_role_name": "沙箱",
+            "permissions": ["browser"],
+            "policies": [
+                {"name": "allowed_backend_types", "value": "docker,opensandbox,filesystem"},
+            ],
+        },
+    )
+    assert created.status_code == 201, created.text
+    assert created.json()["allowed_backend_types"] == ["filesystem", "docker", "opensandbox"]
+    assert created.json()["policies"] == [
+        {"name": "allowed_backend_types", "value": "filesystem,docker,opensandbox"},
+    ]
+
+    unknown = await c.post(
+        "/api/users/roles",
+        headers=auth,
+        json={
+            "user_role_name": "坏类型",
+            "permissions": ["browser"],
+            "policies": [{"name": "allowed_backend_types", "value": "docker,nope"}],
+        },
+    )
+    assert unknown.status_code == 400, unknown.text
+
+    user = await c.post(
+        "/api/users",
+        headers=auth,
+        json={
+            "username": "boxed",
+            "password": TEST_PASSWORD,
+            "role": created.json()["user_role_id"],
+            "create_default_expert": False,
+        },
+    )
+    assert user.status_code == 201, user.text
+    assert user.json()["allowed_backend_types"] == ["filesystem", "docker", "opensandbox"]
+
+    token = await login(c, username="boxed", password=TEST_PASSWORD)
+    me = await c.get("/api/auth/me", headers=bearer(token))
+    assert me.status_code == 200, me.text
+    assert me.json()["allowed_backend_types"] == ["filesystem", "docker", "opensandbox"]
+    user_auth = bearer(token)
+
+    denied = await c.post(
+        "/api/agents",
+        headers=user_auth,
+        json={
+            "name": "host",
+            "config": {"backend": {"type": "local_shell", "root_dir": "/", "virtual_mode": True}},
+        },
+    )
+    assert denied.status_code == 403, denied.text
+    assert denied.json()["error"]["code"] == "BACKEND_TYPE_NOT_ALLOWED"
+
+    omitted = await c.post(
+        "/api/agents",
+        headers=user_auth,
+        json={"name": "omitted", "config": {}},
+    )
+    assert omitted.status_code == 403, omitted.text
+    assert omitted.json()["error"]["code"] == "BACKEND_TYPE_NOT_ALLOWED"
+
+    created_agent = await c.post(
+        "/api/agents",
+        headers=user_auth,
+        json={
+            "name": "files",
+            "config": {"backend": {"type": "filesystem", "root_dir": "/", "virtual_mode": True}},
+        },
+    )
+    assert created_agent.status_code == 201, created_agent.text
+    agent_id = created_agent.json()["agent_id"]
+
+    kept = await c.patch(
+        f"/api/agents/{agent_id}",
+        headers=user_auth,
+        json={
+            "name": "files-renamed",
+            "config": {"backend": {"type": "filesystem", "root_dir": "/", "virtual_mode": True}},
+        },
+    )
+    assert kept.status_code == 200, kept.text
+
+    tightened = await c.patch(
+        f"/api/users/{user.json()['id']}",
+        headers=auth,
+        json={"allowed_backend_types": ["docker"]},
+    )
+    assert tightened.status_code == 200, tightened.text
+    assert tightened.json()["allowed_backend_types"] == ["docker"]
+
+    still_kept = await c.patch(
+        f"/api/agents/{agent_id}",
+        headers=user_auth,
+        json={
+            "name": "files-kept",
+            "config": {"backend": {"type": "filesystem", "root_dir": "/", "virtual_mode": True}},
+        },
+    )
+    assert still_kept.status_code == 200, still_kept.text
+
+    switched = await c.patch(
+        f"/api/agents/{agent_id}",
+        headers=user_auth,
+        json={
+            "config": {"backend": {"type": "local_shell", "root_dir": "/", "virtual_mode": True}},
+        },
+    )
+    assert switched.status_code == 403, switched.text
+    assert switched.json()["error"]["code"] == "BACKEND_TYPE_NOT_ALLOWED"
+
+    cleared = await c.patch(
+        f"/api/users/{user.json()['id']}",
+        headers=auth,
+        json={"role": "user"},
+    )
+    assert cleared.status_code == 200, cleared.text
+    assert cleared.json()["allowed_backend_types"] is None
diff --git a/tests/unit/backend/test_grep_safety.py b/tests/unit/backend/test_grep_safety.py
index 09339706c1..4e60377630 100644
--- a/tests/unit/backend/test_grep_safety.py
+++ b/tests/unit/backend/test_grep_safety.py
@@ -109,7 +109,7 @@ def test_python_search_does_not_walk_proc() -> None:
 
 def test_dockerfiles_install_ripgrep() -> None:
     root = Path(__file__).resolve().parents[3]
-    for rel in ("docker/Dockerfile", "fnos/docker/Dockerfile"):
+    for rel in ("deploy/docker/Dockerfile", "fnos/docker/Dockerfile"):
         text = (root / rel).read_text(encoding="utf-8")
         assert "ripgrep" in text, f"{rel} must install ripgrep"
 
diff --git a/tests/unit/test_docker_compose_database_env.py b/tests/unit/test_docker_compose_database_env.py
index 23fef9f7f6..16c85d4cf0 100644
--- a/tests/unit/test_docker_compose_database_env.py
+++ b/tests/unit/test_docker_compose_database_env.py
@@ -21,10 +21,10 @@ def _compose_environment_entries(compose_text: str) -> str:
 
 
 def test_docker_compose_forwards_database_env_keys() -> None:
-    """docker/.env alone does not inject vars — they must be listed under environment."""
+    """deploy/docker/.env alone does not inject vars — they must be listed under environment."""
     repo = Path(__file__).resolve().parents[2]
     for name in ("docker-compose.yml", "docker-compose.cn.yml"):
-        text = (repo / "docker" / name).read_text(encoding="utf-8")
+        text = (repo / "deploy" / "docker" / name).read_text(encoding="utf-8")
         env_text = _compose_environment_entries(text)
         missing = [k for k in _DATABASE_ENV_KEYS if f"{k}=" not in env_text]
         assert not missing, f"{name} environment missing: {missing}"
diff --git a/tests/unit/test_docker_entrypoint.py b/tests/unit/test_docker_entrypoint.py
index 9528170de7..fb99990dc5 100644
--- a/tests/unit/test_docker_entrypoint.py
+++ b/tests/unit/test_docker_entrypoint.py
@@ -21,7 +21,7 @@
 bash_only = pytest.mark.skipif(bash_exe is None, reason="requires a bash shell")
 
 REPO = Path(__file__).resolve().parents[2]
-ENTRYPOINT = REPO / "docker" / "docker-entrypoint.sh"
+ENTRYPOINT = REPO / "deploy" / "docker" / "docker-entrypoint.sh"
 
 
 def _bash_path(path: Path) -> str:
diff --git a/tests/unit/test_docker_knowledge_dependencies.py b/tests/unit/test_docker_knowledge_dependencies.py
index 888232e0c0..b6491b640a 100644
--- a/tests/unit/test_docker_knowledge_dependencies.py
+++ b/tests/unit/test_docker_knowledge_dependencies.py
@@ -9,7 +9,7 @@
 def test_docker_syncs_retain_knowledge_extras() -> None:
     """A later exact uv sync must not prune extras installed in an earlier layer."""
     repo = Path(__file__).resolve().parents[2]
-    dockerfile = (repo / "docker" / "Dockerfile").read_text(encoding="utf-8")
+    dockerfile = (repo / "deploy" / "docker" / "Dockerfile").read_text(encoding="utf-8")
     commands = dockerfile.replace("\\\n", " ").splitlines()
     syncs = [shlex.split(line.strip()) for line in commands if "uv sync " in line]
     assert len(syncs) == 2
@@ -42,7 +42,7 @@ def _desktop_smoke_import(dockerfile: str) -> bool:
 def test_fnos_source_dockerfile_installs_knowledge_extras() -> None:
     """The manual FnOS source image must bake the same knowledge runtimes.
 
-    Published FnOS Docker packages pull the image built from docker/Dockerfile
+    Published FnOS Docker packages pull the image built from deploy/docker/Dockerfile
     and do not build this file.
     """
     repo = Path(__file__).resolve().parents[2]
@@ -56,7 +56,7 @@ def test_variant_is_validated_and_compiler_is_purged_in_the_install_layer() -> N
     """A typo must not silently build the full image, and gcc must not stay in it."""
     repo = Path(__file__).resolve().parents[2]
     for rel, install_marker in (
-        ("docker/Dockerfile", "uv sync "),
+        ("deploy/docker/Dockerfile", "uv sync "),
         ("fnos/docker/Dockerfile", "uv pip install "),
     ):
         text = (repo / rel).read_text(encoding="utf-8")
@@ -78,7 +78,7 @@ def test_project_sync_purges_compiler_only_when_it_is_installed() -> None:
     with ``Unable to locate package build-essential``.
     """
     repo = Path(__file__).resolve().parents[2]
-    text = (repo / "docker" / "Dockerfile").read_text(encoding="utf-8")
+    text = (repo / "deploy" / "docker" / "Dockerfile").read_text(encoding="utf-8")
     layers = [layer for layer in text.split("\nRUN ") if "uv sync " in layer]
     assert len(layers) == 2
     project = layers[1]
@@ -89,7 +89,7 @@ def test_project_sync_purges_compiler_only_when_it_is_installed() -> None:
 def test_images_bake_desktop_without_starting_or_downloading_laya() -> None:
     """Both images install the desktop stack and leave Xvnc stopped."""
     repo = Path(__file__).resolve().parents[2]
-    bake = (repo / "docker" / "bake-desktop.sh").read_text(encoding="utf-8")
+    bake = (repo / "deploy" / "docker" / "bake-desktop.sh").read_text(encoding="utf-8")
     install = (repo / "src/octop/infra/control/desktop/scripts/linux/v1.0/install.sh").read_text(
         encoding="utf-8"
     )
@@ -100,7 +100,7 @@ def test_images_bake_desktop_without_starting_or_downloading_laya() -> None:
     assert "firefox-esr" in bake
     assert "chromium-browser" in install
     assert 'if [ "$NO_START" = 1 ]' in install
-    for rel in ("docker/Dockerfile", "fnos/docker/Dockerfile"):
+    for rel in ("deploy/docker/Dockerfile", "fnos/docker/Dockerfile"):
         text = (repo / rel).read_text(encoding="utf-8")
         assert "bake-desktop.sh" in text
         assert "playwright install" not in text
diff --git a/tests/unit/test_docker_nodejs.py b/tests/unit/test_docker_nodejs.py
index 9a612e947c..ab2f5e700c 100644
--- a/tests/unit/test_docker_nodejs.py
+++ b/tests/unit/test_docker_nodejs.py
@@ -8,12 +8,12 @@
 def test_images_ship_nodejs_runtime() -> None:
     """Both Dockerfiles copy Node 20 from the frontend stage into the runtime.
 
-    Published FnOS Docker packages pull the image built from docker/Dockerfile.
+    Published FnOS Docker packages pull the image built from deploy/docker/Dockerfile.
     The FnOS source Dockerfile must keep the same runtime so a manual build
     does not drop Node.
     """
     repo = Path(__file__).resolve().parents[2]
-    for rel in ("docker/Dockerfile", "fnos/docker/Dockerfile"):
+    for rel in ("deploy/docker/Dockerfile", "fnos/docker/Dockerfile"):
         text = (repo / rel).read_text(encoding="utf-8")
         assert "COPY --from=frontend-builder /usr/local/bin/node /usr/local/bin/node" in text
         assert (
diff --git a/tests/unit/test_docker_nofile.py b/tests/unit/test_docker_nofile.py
index 43f33c860a..1592995ab0 100644
--- a/tests/unit/test_docker_nofile.py
+++ b/tests/unit/test_docker_nofile.py
@@ -11,9 +11,9 @@
 @pytest.mark.parametrize(
     "relative_path",
     [
-        "docker/docker-compose.yml",
-        "docker/docker-compose.cn.yml",
-        "docker/docker-compose.mobile.yml",
+        "deploy/docker/docker-compose.yml",
+        "deploy/docker/docker-compose.cn.yml",
+        "deploy/docker/docker-compose.mobile.yml",
         "fnos/docker/app/docker/docker-compose.yaml",
     ],
 )
diff --git a/tests/unit/test_langfuse_env_names.py b/tests/unit/test_langfuse_env_names.py
index c4fd369abd..519a150cf0 100644
--- a/tests/unit/test_langfuse_env_names.py
+++ b/tests/unit/test_langfuse_env_names.py
@@ -1,6 +1,6 @@
 """Every Langfuse variable shipped to the container must have a reader.
 
-`.env.example` and `docker/docker-compose.yml` advertise the observability
+`.env.example` and `deploy/docker/docker-compose.yml` advertise the observability
 knobs to self-hosters. Octop itself keeps the enable switch in the settings
 table (`observability_langfuse_enabled`), while the credentials fall back to
 the Langfuse SDK's own environment variables — so a name neither side reads
@@ -16,7 +16,7 @@
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 ENV_EXAMPLE = REPO_ROOT / ".env.example"
-COMPOSE = REPO_ROOT / "docker" / "docker-compose.yml"
+COMPOSE = REPO_ROOT / "deploy" / "docker" / "docker-compose.yml"
 
 
 def _shipped_langfuse_names() -> set[str]:
diff --git a/tests/unit/users/test_resource_policy.py b/tests/unit/users/test_resource_policy.py
index 3700684d72..2c66654543 100644
--- a/tests/unit/users/test_resource_policy.py
+++ b/tests/unit/users/test_resource_policy.py
@@ -14,6 +14,7 @@
 from octop.infra.db.repos.users import UserRepo
 from octop.infra.errors import ErrorCode, OctopError
 from octop.infra.users.resource_policy import (
+    POLICY_ALLOWED_BACKEND_TYPES,
     POLICY_MAX_AGENTS,
     POLICY_TOKEN_QUOTA,
     POLICY_WORKSPACE_ROOT_DIR,
@@ -22,9 +23,11 @@
     assert_backend_within_user_root,
     assert_token_quota_available,
     clamp_backend_to_workspace_root,
+    normalize_allowed_backend_types,
     normalize_workspace_root_dir,
     persisted_workspace_within_root,
     public_policy_fields,
+    raise_if_backend_types_disallowed,
 )
 
 
@@ -326,6 +329,7 @@ def test_user_policy_repo_named_rows(db: SqlitePool, tmp_path: Path) -> None:
         "workspace_root_dir": str(jail),
         "token_quota": 42,
         "max_agents": None,
+        "allowed_backend_types": None,
     }
     root = policies.get(uid, POLICY_WORKSPACE_ROOT_DIR)
     assert root is not None
@@ -465,3 +469,91 @@ def test_migration_rebuilds_legacy_kv_table(tmp_path: Path) -> None:
         cols = {r["name"] for r in conn.execute("PRAGMA table_info(user_policies)")}
     assert "key" not in cols
     assert "policy_id" in cols
+
+
+def test_normalize_allowed_backend_types_orders_and_rejects_unknown() -> None:
+    assert normalize_allowed_backend_types(None) is None
+    assert normalize_allowed_backend_types("") is None
+    assert normalize_allowed_backend_types([]) is None
+    assert (
+        normalize_allowed_backend_types(["docker", "opensandbox", "filesystem", "docker"])
+        == "filesystem,docker,opensandbox"
+    )
+    assert normalize_allowed_backend_types(["shell", "docker"]) == "local_shell,docker"
+    assert normalize_allowed_backend_types(["local_shell", "shell"]) == "local_shell"
+    with pytest.raises(OctopError) as exc:
+        normalize_allowed_backend_types(["docker", "nope"])
+    assert exc.value.code is ErrorCode.FORBIDDEN
+
+
+def test_raise_if_backend_types_disallowed_walks_named_and_composite(db: SqlitePool) -> None:
+    users = UserRepo(db)
+    policies = UserPolicyRepo(db)
+    uid = users.create(username="alice", password_hash="h", role="user")
+    kinds = {"box": "docker", "disk": "filesystem", "host": "shell"}
+
+    def named_kind(name: str) -> str | None:
+        return kinds.get(name)
+
+    raise_if_backend_types_disallowed(
+        policies,
+        uid,
+        {"type": "local_shell"},
+        named_kind=named_kind,
+    )
+    policies.set(uid, POLICY_ALLOWED_BACKEND_TYPES, "docker,opensandbox")
+    spec = {
+        "type": "composite",
+        "default": {"type": "named", "name": "box"},
+        "routes": {"/data": {"type": "named", "name": "disk"}},
+    }
+    with pytest.raises(OctopError) as exc:
+        raise_if_backend_types_disallowed(policies, uid, spec, named_kind=named_kind)
+    assert exc.value.code is ErrorCode.BACKEND_TYPE_NOT_ALLOWED
+    assert exc.value.details["types"] == "filesystem"
+    raise_if_backend_types_disallowed(
+        policies,
+        uid,
+        {"type": "named", "name": "box"},
+        named_kind=named_kind,
+        require_present=True,
+    )
+    with pytest.raises(OctopError) as missing:
+        raise_if_backend_types_disallowed(
+            policies,
+            uid,
+            None,
+            named_kind=named_kind,
+            require_present=True,
+        )
+    assert missing.value.details["types"] == "local_shell"
+    # A stored filesystem route can stay; a new shell route cannot.
+    raise_if_backend_types_disallowed(
+        policies,
+        uid,
+        spec,
+        named_kind=named_kind,
+        previous=spec,
+    )
+    with pytest.raises(OctopError) as shell_blocked:
+        raise_if_backend_types_disallowed(
+            policies,
+            uid,
+            {"type": "named", "name": "host"},
+            named_kind=named_kind,
+            previous=spec,
+        )
+    assert shell_blocked.value.details["types"] == "local_shell"
+    policies.set(uid, POLICY_ALLOWED_BACKEND_TYPES, "local_shell")
+    raise_if_backend_types_disallowed(
+        policies,
+        uid,
+        {"type": "named", "name": "host"},
+        named_kind=named_kind,
+    )
+    raise_if_backend_types_disallowed(
+        policies,
+        uid,
+        {"type": "local_shell"},
+        named_kind=named_kind,
+    )

From a01c397ef4293c7f926a5a3f4136f25c447fc3c6 Mon Sep 17 00:00:00 2001
From: Alison 
Date: Thu, 12 Nov 2026 17:39:16 +1100
Subject: [PATCH 08/26] feat(dashboard): guided tour for new users (#2949)

* feat(dashboard): add a welcome guide for new users

New users land on an empty chat page with no overview of what Octop
offers. Add a short step-by-step guide that opens on first login and
introduces conversations, experts, model configuration, channels,
knowledge bases and skill packages, with a button on each step that
opens the matching page.

- Store `onboarding_completed` per user in `preferences_json`, exposed
  through GET/PATCH /api/preferences (no schema change).
- Finishing, skipping, closing or jumping to a page marks it done, so
  it does not open again by itself; "Getting started" in the account
  menu reopens it.
- Steps follow the user's permissions; members without the models page
  are pointed at the chat model picker instead.
- zh/en copy under `onboarding.*`.

* feat(dashboard): walk new users through each page with a spotlight tour

Instead of describing pages in a single dialog, the guide now opens each
page in turn and spotlights its sidebar entry with antd Tour:

- Intro card with the mascot and the list of stops, staggered in.
- Each step navigates to its page, pulses the sidebar entry under the
  spotlight, and shows a short description, a tip and a progress bar.
  Arrow keys move between steps; Esc exits.
- A wrap-up card with quick links to chat or create an expert.
- On mobile the nav lives in a closed drawer, so the card is centered.
- Animations are disabled under prefers-reduced-motion.

Sidebar items expose `data-nav-key` so the tour can find its targets.

---------

Co-authored-by: Alison <20137720+alison-xx@users.noreply.github.com>
---
 dashboard/src/api/modules/preferences.ts      |   3 +
 dashboard/src/components/AvatarDropdown.tsx   |  21 +
 .../OnboardingGuide.module.less               | 367 ++++++++++++++++++
 .../OnboardingGuide/OnboardingGuide.test.tsx  | 168 ++++++++
 .../OnboardingGuide/OnboardingGuide.tsx       | 313 +++++++++++++++
 .../src/components/OnboardingGuide/index.ts   |   1 +
 .../OnboardingGuide/onboardingSteps.test.ts   |  64 +++
 .../OnboardingGuide/onboardingSteps.ts        |  76 ++++
 dashboard/src/layouts/Sidebar.tsx             |  25 +-
 .../src/layouts/SidebarCollapsedIconNav.tsx   |   1 +
 dashboard/src/locales/en.json                 |  56 +++
 dashboard/src/locales/zh.json                 |  56 +++
 src/octop/api/routers/preferences.py          |  13 +
 src/octop/infra/users/manager.py              |   8 +
 src/octop/infra/users/preferences.py          |  15 +
 tests/integration/test_preferences_api.py     |  39 ++
 tests/unit/users/test_preferences.py          |  25 ++
 17 files changed, 1249 insertions(+), 2 deletions(-)
 create mode 100644 dashboard/src/components/OnboardingGuide/OnboardingGuide.module.less
 create mode 100644 dashboard/src/components/OnboardingGuide/OnboardingGuide.test.tsx
 create mode 100644 dashboard/src/components/OnboardingGuide/OnboardingGuide.tsx
 create mode 100644 dashboard/src/components/OnboardingGuide/index.ts
 create mode 100644 dashboard/src/components/OnboardingGuide/onboardingSteps.test.ts
 create mode 100644 dashboard/src/components/OnboardingGuide/onboardingSteps.ts

diff --git a/dashboard/src/api/modules/preferences.ts b/dashboard/src/api/modules/preferences.ts
index 3ee76e4bc3..5862b05cd3 100644
--- a/dashboard/src/api/modules/preferences.ts
+++ b/dashboard/src/api/modules/preferences.ts
@@ -30,6 +30,8 @@ export interface UserPreferences {
     { mode: "auto" | "enabled" | "disabled"; effort?: string | null }
   >;
   sidebar_nav?: SidebarNavLayoutPref | null;
+  /** True once the user finished or skipped the welcome guide. */
+  onboarding_completed?: boolean;
 }
 
 export type PatchPreferencesBody = {
@@ -38,6 +40,7 @@ export type PatchPreferencesBody = {
   preferred_model?: string | null;
   model_reasoning?: UserPreferences["model_reasoning"];
   sidebar_nav?: SidebarNavLayoutPref | null;
+  onboarding_completed?: boolean;
 };
 
 export const preferencesApi = {
diff --git a/dashboard/src/components/AvatarDropdown.tsx b/dashboard/src/components/AvatarDropdown.tsx
index 920bd0142a..1c756c3153 100644
--- a/dashboard/src/components/AvatarDropdown.tsx
+++ b/dashboard/src/components/AvatarDropdown.tsx
@@ -24,6 +24,7 @@ import {
   KeyRound,
   ShieldCheck,
   SlidersHorizontal,
+  Compass,
 } from "lucide-react";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -85,6 +86,8 @@ interface AvatarDropdownProps {
   onBeforeOpenSettings?: () => void;
   /** Opens the sidebar layout editor. Omitted when that editor is unavailable. */
   onCustomizeNav?: () => void;
+  /** Reopens the welcome guide. Omitted when the guide is not mounted. */
+  onOpenOnboarding?: () => void;
 }
 
 export default function AvatarDropdown({
@@ -94,6 +97,7 @@ export default function AvatarDropdown({
   compact = false,
   onBeforeOpenSettings,
   onCustomizeNav,
+  onOpenOnboarding,
 }: AvatarDropdownProps) {
   const { t, i18n } = useTranslation();
   const navigate = useNavigate();
@@ -245,6 +249,12 @@ export default function AvatarDropdown({
     deferOpen(() => onCustomizeNav?.());
   };
 
+  const openOnboarding = () => {
+    setMenuOpen(false);
+    onBeforeOpenSettings?.();
+    deferOpen(() => onOpenOnboarding?.());
+  };
+
   const closeSettings = () => setSettingsOpen(false);
 
   useEffect(() => {
@@ -334,6 +344,17 @@ export default function AvatarDropdown({
         {t("account.helpFeedback")}
       
 
+      {onOpenOnboarding ? (
+        
+      ) : null}
+
        :first-child {
+    margin-right: auto;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mascot,
+  .heroTitle,
+  .heroText,
+  .concept,
+  .introActions,
+  .duration,
+  .spark,
+  .doneCheck,
+  .stepHead,
+  .stepIcon,
+  .stepBody,
+  :global([data-onboarding-active]) {
+    animation: none;
+  }
+
+  .spark {
+    display: none;
+  }
+
+  .tourBarFill,
+  .concept {
+    transition: none;
+  }
+}
diff --git a/dashboard/src/components/OnboardingGuide/OnboardingGuide.test.tsx b/dashboard/src/components/OnboardingGuide/OnboardingGuide.test.tsx
new file mode 100644
index 0000000000..1b2e7612c2
--- /dev/null
+++ b/dashboard/src/components/OnboardingGuide/OnboardingGuide.test.tsx
@@ -0,0 +1,168 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter, Route, Routes, useLocation } from "react-router-dom";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { patchMock, userRef } = vi.hoisted(() => ({
+  patchMock: vi.fn(),
+  userRef: {
+    current: { role: "user", permissions: ["knowledge_bases"] } as {
+      role: string;
+      permissions: string[];
+    },
+  },
+}));
+
+vi.mock("../../api/modules/preferences", () => ({
+  preferencesApi: { patch: patchMock },
+}));
+vi.mock("../../hooks/useCurrentUser", () => ({
+  useCurrentUser: () => userRef.current,
+}));
+vi.mock("../../hooks/useIsMobile", () => ({
+  useIsMobile: () => false,
+}));
+
+import OnboardingGuide from "./OnboardingGuide";
+
+function Location() {
+  return 
{useLocation().pathname}
; +} + +function renderGuide(onClose = vi.fn()) { + render( + +
nav
+ + + } /> + +
, + ); + return onClose; +} + +const button = (name: string) => screen.getByRole("button", { name }); +const location = () => screen.getByTestId("location").textContent; + +describe("OnboardingGuide", () => { + beforeEach(() => { + patchMock.mockReset(); + patchMock.mockResolvedValue({}); + userRef.current = { role: "user", permissions: ["knowledge_bases"] }; + }); + + it("introduces only the pages the user can open", () => { + renderGuide(); + expect(screen.getByText("onboarding.intro.title")).toBeInTheDocument(); + const concepts = screen + .getAllByRole("listitem") + .map((li) => li.textContent); + expect(concepts).toEqual([ + "onboarding.steps.chat.title", + "onboarding.steps.models.title", + "onboarding.steps.knowledgeBases.title", + ]); + }); + + it("opens each step's page and spotlights its sidebar entry", async () => { + const user = userEvent.setup(); + renderGuide(); + const kbNav = screen.getByText("nav"); + + await user.click(button("onboarding.start")); + expect(location()).toBe("/chat"); + expect(screen.getByText("onboarding.steps.chat.body")).toBeInTheDocument(); + + await user.click(button("onboarding.next")); + expect(location()).toBe("/chat"); + expect( + screen.getByText("onboarding.steps.models.bodyMember"), + ).toBeInTheDocument(); + expect(kbNav).not.toHaveAttribute("data-onboarding-active"); + + await user.click(button("onboarding.next")); + expect(location()).toBe("/knowledge-bases"); + expect(kbNav).toHaveAttribute("data-onboarding-active"); + expect(screen.getByRole("progressbar")).toHaveAttribute( + "aria-valuenow", + "3", + ); + + await user.click(button("onboarding.back")); + expect(kbNav).not.toHaveAttribute("data-onboarding-active"); + expect(patchMock).not.toHaveBeenCalled(); + }); + + it("ends on a wrap-up card and records completion", async () => { + const user = userEvent.setup(); + const onClose = renderGuide(); + + await user.click(button("onboarding.start")); + await user.click(button("onboarding.next")); + await user.click(button("onboarding.next")); + await user.click(button("onboarding.finish")); + + expect(screen.getByText("onboarding.done.title")).toBeInTheDocument(); + expect(patchMock).not.toHaveBeenCalled(); + + await user.click(button("onboarding.done.chat")); + expect(location()).toBe("/chat"); + expect(onClose).toHaveBeenCalledTimes(1); + expect(patchMock).toHaveBeenCalledWith({ onboarding_completed: true }); + }); + + it("supports arrow keys and Esc during the tour", async () => { + const user = userEvent.setup(); + const onClose = renderGuide(); + + await user.click(button("onboarding.start")); + act(() => { + fireEvent.keyDown(window, { key: "ArrowRight" }); + }); + act(() => { + fireEvent.keyDown(window, { key: "ArrowRight" }); + }); + expect(location()).toBe("/knowledge-bases"); + act(() => { + fireEvent.keyDown(window, { key: "ArrowLeft" }); + }); + expect( + screen.getByText("onboarding.steps.models.bodyMember"), + ).toBeInTheDocument(); + + act(() => { + fireEvent.keyDown(window, { key: "Escape" }); + }); + expect(onClose).toHaveBeenCalledTimes(1); + expect(patchMock).toHaveBeenCalledWith({ onboarding_completed: true }); + }); + + it("records completion when postponed from the intro", async () => { + const user = userEvent.setup(); + const onClose = renderGuide(); + + await user.click(button("onboarding.later")); + + expect(onClose).toHaveBeenCalledTimes(1); + expect(patchMock).toHaveBeenCalledWith({ onboarding_completed: true }); + expect(location()).toBe("/token-usage"); + }); + + it("offers the experts page at the end when the user can open it", async () => { + userRef.current = { role: "admin", permissions: [] }; + const user = userEvent.setup(); + renderGuide(); + + await user.click(button("onboarding.start")); + for (let i = 0; i < 5; i += 1) { + await user.click(button("onboarding.next")); + } + expect(location()).toBe("/skill-packages"); + await user.click(button("onboarding.finish")); + await user.click(button("onboarding.done.experts")); + + expect(location()).toBe("/experts"); + expect(patchMock).toHaveBeenCalledWith({ onboarding_completed: true }); + }); +}); diff --git a/dashboard/src/components/OnboardingGuide/OnboardingGuide.tsx b/dashboard/src/components/OnboardingGuide/OnboardingGuide.tsx new file mode 100644 index 0000000000..0e72d97958 --- /dev/null +++ b/dashboard/src/components/OnboardingGuide/OnboardingGuide.tsx @@ -0,0 +1,313 @@ +import { + useCallback, + useEffect, + useMemo, + useState, + type CSSProperties, + type ComponentType, +} from "react"; +import { Button, Modal, Tour, type TourStepProps } from "antd"; +import { + ArrowLeft, + ArrowRight, + BookOpen, + Bot, + Check, + Cpu, + Lightbulb, + MessageSquare, + Package, + Radio, + type LucideProps, +} from "lucide-react"; +import { useNavigate } from "react-router-dom"; +import { useTranslation } from "react-i18next"; +import cx from "classnames"; + +import { preferencesApi } from "../../api/modules/preferences"; +import { useCurrentUser } from "../../hooks/useCurrentUser"; +import { useIsMobile } from "../../hooks/useIsMobile"; +import { navAllowed } from "../../utils/permissions"; +import { publicUrl } from "../../utils/publicUrl"; +import { + buildOnboardingSteps, + type OnboardingStep, + type OnboardingStepKey, +} from "./onboardingSteps"; +import styles from "./OnboardingGuide.module.less"; + +const STEP_ICONS: Record> = { + chat: MessageSquare, + experts: Bot, + models: Cpu, + channels: Radio, + knowledgeBases: BookOpen, + skillPackages: Package, +}; + +/** Set on the spotlighted sidebar item so CSS can pulse it. */ +const ACTIVE_ATTR = "data-onboarding-active"; + +type Phase = "intro" | "tour" | "done"; + +interface OnboardingGuideProps { + open: boolean; + onClose: () => void; +} + +function navTarget(step: OnboardingStep): HTMLElement | null { + return document.querySelector(`[data-nav-key="${step.navKey}"]`); +} + +/** + * Welcome guide: an intro card, a spotlight tour that opens each page and + * highlights its sidebar entry, then a short wrap-up. + * + * Leaving it at any point (finish, skip, close, Esc) marks it done for this + * user on the server, so it does not open by itself again. + */ +export default function OnboardingGuide({ + open, + onClose, +}: OnboardingGuideProps) { + const { t } = useTranslation(); + const navigate = useNavigate(); + const isMobile = useIsMobile(); + const user = useCurrentUser(); + const steps = useMemo(() => buildOnboardingSteps(user), [user]); + const [phase, setPhase] = useState("intro"); + const [current, setCurrent] = useState(0); + + useEffect(() => { + if (!open) return; + setPhase("intro"); + setCurrent(0); + }, [open]); + + const finish = useCallback( + (path?: string) => { + onClose(); + if (path) navigate(path); + void preferencesApi + .patch({ onboarding_completed: true }) + .catch(() => undefined); + }, + [navigate, onClose], + ); + + const touring = open && phase === "tour"; + const step = steps[Math.min(current, steps.length - 1)]; + const isLast = current >= steps.length - 1; + + const goNext = useCallback(() => { + if (isLast) setPhase("done"); + else setCurrent((i) => i + 1); + }, [isLast]); + const goBack = useCallback(() => { + setCurrent((i) => Math.max(0, i - 1)); + }, []); + + // Open the step's page, then pulse its sidebar entry under the spotlight. + useEffect(() => { + if (!touring) return; + navigate(step.path); + const el = isMobile ? null : navTarget(step); + el?.setAttribute(ACTIVE_ATTR, ""); + return () => el?.removeAttribute(ACTIVE_ATTR); + }, [touring, step, navigate, isMobile]); + + useEffect(() => { + if (!touring) return; + const onKey = (e: KeyboardEvent) => { + const el = e.target instanceof Element ? e.target : null; + if (el?.closest("input, textarea, [contenteditable=true]")) return; + if (e.key === "ArrowRight") goNext(); + else if (e.key === "ArrowLeft") goBack(); + else if (e.key === "Escape") finish(); + else return; + e.preventDefault(); + }; + window.addEventListener("keydown", onKey); + return () => window.removeEventListener("keydown", onKey); + }, [touring, goNext, goBack, finish]); + + const tourSteps: TourStepProps[] = steps.map((s, i) => { + const Icon = STEP_ICONS[s.key]; + const member = s.variant === "member"; + return { + // Mobile keeps the nav in a closed drawer, so the card stays centered. + target: isMobile ? null : () => navTarget(s) as HTMLElement, + placement: isMobile ? "center" : "right", + title: ( +
+ + + + {t(`onboarding.steps.${s.key}.title`)} +
+ ), + description: ( +
+

+ {t(`onboarding.steps.${s.key}.${member ? "bodyMember" : "body"}`)} +

+

+ + + {t(`onboarding.steps.${s.key}.${member ? "tipMember" : "tip"}`)} + +

+
+ ), + }; + }); + + const progressLabel = t("onboarding.progress", { + current: current + 1, + total: steps.length, + }); + + return ( + <> + finish()} + footer={null} + width={isMobile ? "calc(100vw - 32px)" : 560} + centered + destroyOnHidden + className={styles.modal} + > +
+ +

{t("onboarding.intro.title")}

+

{t("onboarding.intro.body")}

+
    + {steps.map((s, i) => { + const Icon = STEP_ICONS[s.key]; + return ( +
  • + + {t(`onboarding.steps.${s.key}.title`)} +
  • + ); + })} +
+
+ + +
+ + {t("onboarding.intro.duration", { count: steps.length })} + {!isMobile && ` · ${t("onboarding.keyboardHint")}`} + +
+
+ + finish()} + steps={tourSteps} + rootClassName={styles.tour} + disabledInteraction + gap={{ offset: 6, radius: 10 }} + indicatorsRender={(cur, total) => ( +
+
+ +
+ + {cur + 1} / {total} + +
+ )} + actionsRender={() => ( +
+ + {current > 0 && ( + + )} + +
+ )} + /> + + finish()} + footer={null} + width={isMobile ? "calc(100vw - 32px)" : 440} + centered + destroyOnHidden + className={styles.modal} + > +
+
+ {Array.from({ length: 12 }, (_, i) => ( + + ))} + + + +
+

{t("onboarding.done.title")}

+

{t("onboarding.done.body")}

+
+ + {navAllowed(user, "experts") && ( + + )} +
+
+
+ + ); +} diff --git a/dashboard/src/components/OnboardingGuide/index.ts b/dashboard/src/components/OnboardingGuide/index.ts new file mode 100644 index 0000000000..9409bcf54b --- /dev/null +++ b/dashboard/src/components/OnboardingGuide/index.ts @@ -0,0 +1 @@ +export { default } from "./OnboardingGuide"; diff --git a/dashboard/src/components/OnboardingGuide/onboardingSteps.test.ts b/dashboard/src/components/OnboardingGuide/onboardingSteps.test.ts new file mode 100644 index 0000000000..3d32b3d11a --- /dev/null +++ b/dashboard/src/components/OnboardingGuide/onboardingSteps.test.ts @@ -0,0 +1,64 @@ +import { describe, expect, it } from "vitest"; + +import { buildOnboardingSteps } from "./onboardingSteps"; + +const keys = (steps: ReturnType) => + steps.map((s) => s.key); + +describe("buildOnboardingSteps", () => { + it("tours admins through every page, models included", () => { + const steps = buildOnboardingSteps({ role: "admin", permissions: [] }); + expect(keys(steps)).toEqual([ + "chat", + "experts", + "models", + "channels", + "knowledgeBases", + "skillPackages", + ]); + expect(steps.find((s) => s.key === "models")).toEqual({ + key: "models", + path: "/admin/models", + navKey: "models", + variant: "default", + }); + // Every step spotlights a real sidebar entry on the page it opens. + expect(steps.map((s) => s.navKey)).toEqual([ + "chat", + "experts", + "models", + "channels", + "knowledge-bases", + "skill-packages", + ]); + }); + + it("points members without the models page at the chat model picker", () => { + const steps = buildOnboardingSteps({ + role: "user", + permissions: ["experts", "channels", "knowledge_bases", "skill_packages"], + }); + expect(keys(steps)).toEqual([ + "chat", + "experts", + "models", + "channels", + "knowledgeBases", + "skillPackages", + ]); + expect(steps.find((s) => s.key === "models")).toEqual({ + key: "models", + path: "/chat", + navKey: "chat", + variant: "member", + }); + }); + + it("drops steps for pages the user cannot open", () => { + const steps = buildOnboardingSteps({ + role: "user", + permissions: ["knowledge_bases"], + }); + expect(keys(steps)).toEqual(["chat", "models", "knowledgeBases"]); + }); +}); diff --git a/dashboard/src/components/OnboardingGuide/onboardingSteps.ts b/dashboard/src/components/OnboardingGuide/onboardingSteps.ts new file mode 100644 index 0000000000..eaf8827840 --- /dev/null +++ b/dashboard/src/components/OnboardingGuide/onboardingSteps.ts @@ -0,0 +1,76 @@ +import { navAllowed, type PermissionHolder } from "../../utils/permissions"; + +export type OnboardingStepKey = + | "chat" + | "experts" + | "models" + | "channels" + | "knowledgeBases" + | "skillPackages"; + +export interface OnboardingStep { + key: OnboardingStepKey; + /** Page the tour opens for this step. */ + path: string; + /** Sidebar item (``data-nav-key``) the tour spotlights on that page. */ + navKey: string; + /** Copy variant under ``onboarding.steps.``. */ + variant: "default" | "member"; +} + +/** + * Tour steps, filtered to the pages this user can open. + * + * Model providers are admin-managed; members without the models page still get + * the step, pointed at the chat input's model picker instead. + */ +export function buildOnboardingSteps( + user: PermissionHolder | null | undefined, +): OnboardingStep[] { + const steps: OnboardingStep[] = [ + { key: "chat", path: "/chat", navKey: "chat", variant: "default" }, + ]; + if (navAllowed(user, "experts")) { + steps.push({ + key: "experts", + path: "/experts", + navKey: "experts", + variant: "default", + }); + } + steps.push( + navAllowed(user, "models") + ? { + key: "models", + path: "/admin/models", + navKey: "models", + variant: "default", + } + : { key: "models", path: "/chat", navKey: "chat", variant: "member" }, + ); + if (navAllowed(user, "channels")) { + steps.push({ + key: "channels", + path: "/personalization/channels", + navKey: "channels", + variant: "default", + }); + } + if (navAllowed(user, "knowledge-bases")) { + steps.push({ + key: "knowledgeBases", + path: "/knowledge-bases", + navKey: "knowledge-bases", + variant: "default", + }); + } + if (navAllowed(user, "skill-packages")) { + steps.push({ + key: "skillPackages", + path: "/skill-packages", + navKey: "skill-packages", + variant: "default", + }); + } + return steps; +} diff --git a/dashboard/src/layouts/Sidebar.tsx b/dashboard/src/layouts/Sidebar.tsx index 7596b19a05..eafffaa8c1 100644 --- a/dashboard/src/layouts/Sidebar.tsx +++ b/dashboard/src/layouts/Sidebar.tsx @@ -1,4 +1,4 @@ -import { useCallback, useEffect, useMemo, useState } from "react"; +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import { useLocation, useNavigate } from "react-router-dom"; import { useTranslation } from "react-i18next"; import type { TFunction } from "i18next"; @@ -43,6 +43,7 @@ import { } from "./sidebarNav"; import { sectionsFromLayout, type SidebarNavLayout } from "./sidebarNavLayout"; import SidebarNavCustomizer from "./SidebarNavCustomizer"; +import OnboardingGuide from "../components/OnboardingGuide"; import styles from "./Sidebar.module.less"; import { typeSize } from "../utils/mobileTypeScale"; @@ -174,6 +175,7 @@ function NavItemButton({ return (
(null); const [customizerOpen, setCustomizerOpen] = useState(false); + const [onboardingOpen, setOnboardingOpen] = useState(false); + const onboardingChecked = useRef(false); const navSections = useMemo( () => sectionsFromLayout(catalog, savedLayout), [catalog, savedLayout], @@ -449,7 +453,14 @@ export default function Sidebar({ void preferencesApi .get() .then((prefs) => { - if (!cancelled) setSavedLayout(prefs.sidebar_nav ?? null); + if (cancelled) return; + setSavedLayout(prefs.sidebar_nav ?? null); + // Open the welcome guide once per session for users who have not + // finished or skipped it yet. + if (!onboardingChecked.current) { + onboardingChecked.current = true; + if (!prefs.onboarding_completed) setOnboardingOpen(true); + } }) .catch(() => { /* keep the default nav */ @@ -550,6 +561,7 @@ export default function Sidebar({ compact={isRailCollapsed} onBeforeOpenSettings={isMobile && !collapsed ? onToggle : undefined} onCustomizeNav={() => setCustomizerOpen(true)} + onOpenOnboarding={() => setOnboardingOpen(true)} />
); @@ -564,6 +576,13 @@ export default function Sidebar({ /> ); + const onboarding = ( + setOnboardingOpen(false)} + /> + ); + const primaryItems = navSections.find((section) => !section.id)?.items ?? []; const namedSections = navSections.filter((section) => section.id); const firstNamed = namedSections[0]; @@ -788,6 +807,7 @@ export default function Sidebar({ > {userFooter} {customizer} + {onboarding} ); @@ -855,6 +875,7 @@ export default function Sidebar({ {userFooter} {customizer} + {onboarding} ); diff --git a/dashboard/src/layouts/SidebarCollapsedIconNav.tsx b/dashboard/src/layouts/SidebarCollapsedIconNav.tsx index d3b2d7a594..9e2a88264b 100644 --- a/dashboard/src/layouts/SidebarCollapsedIconNav.tsx +++ b/dashboard/src/layouts/SidebarCollapsedIconNav.tsx @@ -41,6 +41,7 @@ export default function SidebarCollapsedIconNav({ >