中/EN
实战 SOP
实战 SOP

Octop 自托管 AI 助手部署 SOP

Octop 自托管部署实操 SOP：先给"该不该自托管"的决策口径，再走四条安装路径对照（一键脚本 / Windows PowerShell / Docker Compose / 腾讯云 Lighthouse 与 CVM 官方镜像市场），逐字按官方 README 执行 octop init 与 octop run（默认端口 8088），首次登录立即改默认凭据（README 未写死默认密码、第三方评测口径为 admin/octop、Docker 初始化则生成随机密码），随后配模型（OpenAI 兼容/Ollama/近 20 家）、专家与 MBTI、连接器（腾讯文档/OAuth/MCP）与 IM 通道，最后 Docker Compose 与 PostgreSQL 生产化，附 6 条踩坑速查与 10 条上线前 checklist。

发布于 2026年9月17日8 分钟阅读
<!-- octop-deploy-sop | sop | Octop 自托管 AI 助手部署 SOP -->

腾讯云在 2026-09-17 发布开源自托管多用户 AI 助手 Octop 1.0 GA（来源：官方公众号；GitHub 仓库 TencentCloud/Octop，语言 Python、许可证 MIT，发布当天实测 3,198 星）。它把 Web 控制台、CLI、IM 通道和定时任务塞进一个进程，所有状态落在 ~/.octop/，控制面数据库默认 SQLite（可切 PostgreSQL）。这是一篇不吹不黑的实操 SOP：从「我到底该不该自托管」一路走到「上线前 checklist」，所有安装命令、配置路径、默认端口逐字以官方 README 为准，一个字符都不自己造。关于这次 GA 的来龙去脉，可以看 Octop 1.0 GA 发布热点。

一、适用判断：先给决策口径，再动手

自托管 Octop 不是「买了就能爽」的玩具，它适合三类人。第一类是数据敏感型：聊天记录、工作区、凭据全在自己机器上，本地优先可离线，PII 脱敏后再出站。第二类是家庭共享型：一个 admin 账号带全家，不同成员各有独立记忆、工作区与专家配置，互不串味。第三类是一人公司或小微团队：愿意花时间管一台服务器，换可控、可离线、可审计。它不适合「只想用 AI、不想运维」的人，如果你连端口转发都嫌烦，云端助手更省心。

判断标准只有一条：你愿不愿意为「数据握在自己手里」付出运维成本。愿意，往下读；不愿意，直接关掉这篇去用 SaaS。如果你还在自托管和云端之间纠结，建议先读 自托管 AI 助手横向对比，把成本账算清楚。需要提醒的是，Octop 是单进程架构，Web 控制台、CLI、IM 通道、定时任务都在一个进程里跑，重启时从控制面数据库重建全部状态——这意味着它省事，但也意味着这台机器的可用性就是服务可用性。还有一层常被忽略：单进程意味着没有外部消息队列或 broker，Web、IM、定时任务都走同一个进程内的处理管线。好处是部署极简、重启安全；代价是这台机器的 CPU、内存、磁盘 IO 直接决定全员体验。所以自托管前先问自己三个问题：机器谁维护、断电断网谁兜底、数据丢了谁负责。三个都能答，再继续。

二、安装路径选择（第 1 张表：路径对照）

README 给出四种装法，各自适合不同人群与硬件。先说结论：要长期跑、给多人用，直接上 Docker Compose；只是想在本机体验，macOS 或 Linux 一条命令脚本最省事；Windows 走 PowerShell 脚本；国内用户图省心，GA 当天上线的腾讯云 Lighthouse 与 CVM 官方镜像市场是最顺的渠道（来源：官方公众号，一条命令部署）。

安装方式适用平台适合人群最低硬件要求
一键脚本（curl 管道）macOS / Linux开发者、快速体验现代多核 CPU、数 GB 内存（进程加模型与向量缓存）；安装器用 uv 在 ~/.octop/ 内建 Python 3.12+ 隔离环境，无需系统预装 Python
Windows PowerShell 脚本Windows 10 / 11Windows 用户同上；安装器同样内置 uv 隔离环境，不碰系统 Python
Docker Compose任意平台（生产推荐）长期运行、多人访问同上；容器化便于备份与升级，数据挂到 ~/.octop 或 OCTOP_DATA
腾讯云 Lighthouse / CVM 官方镜像国内用户（GA 新渠道）不想碰命令行、要一条命令部署以镜像市场实例规格为准（来源：官方公众号，GA 当天同步上线）

macOS 与 Linux 推荐用一行安装器，命令从 README 逐字照抄：

bash
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Windows 用 PowerShell 一行安装：

powershell
irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

生产环境用 Docker Compose，命令同样来自 README：

bash
docker compose -f docker/docker-compose.yml up -d

装完之后，macOS 或 Linux 要开一个新终端，或重新加载 shell 配置，让 ~/.octop/bin 进 PATH：

bash
source ~/.zshrc   # Zsh
# 或
source ~/.bashrc  # Bash

README 还提供可选扩展，比如浏览器自动化（Playwright Chromium）和飞书通道，按需加 --extras 参数即可，细节以 README 的 scripts 说明为准。硬件下限方面，README 的口径是「现代多核 CPU、数 GB 内存给进程与模型或向量缓存、足够磁盘给数据库与工作区」，没有写死具体核数，因此不要拿树莓派当生产机。顺带提醒：安装器不碰系统 Python，所有依赖锁在 ~/.octop/venv 里，所以一台机器上即使已有别的 Python 项目也不冲突。但也别因此就在同一台机器上堆满其它重负载服务，Octop 的模型与向量缓存会吃掉不少内存和磁盘，留足余量才稳。

三、初始化：octop init 与 octop run

装好之后第一步是初始化，建数据库、JWT 密钥和首个管理员账号，全部落在 ~/.octop/：

bash
octop init

README 说这是一个交互式向导，会创建 SQLite 数据库、JWT 密钥和第一个管理员账号。接下来启动，前台跑起 API 与 Web 控制台：

bash
# 前台启动（API + Web 控制台）
octop run

# 自定义监听地址与端口
octop run --host 0.0.0.0 --port 8088

# 注册为系统服务（systemd / launchd / Windows service）
octop service start

启动后打开 **http://127.0.0.1:8088**。注意默认端口就是 8088，这是 README 写死的值，不要凭记忆改成别的。Docker 部署时，首次初始化会生成一个随机管理员密码并写进 /data/.octop/credential.txt，除非你显式设了 OCTOP_DEFAULT_PASSWORD；交互式 octop init 或设置向导会让你自己选密码，要求至少 8 位且含字母与数字。

想用 API 文档？README 明确：/api/docs 默认关闭，要在 config.json 里把 enable_api_docs 设为 true 才开。默认不开是合理的，别为了调试把它长期暴露在公网。

四、首次安全加固：默认密码必须改

这是最容易翻车的一步。默认管理员账号是 admin；默认密码方面，官方 README 未写死，第三方评测口径为 octop，而 Docker 部署首次初始化会生成随机密码写入 credential.txt——无论拿到的是哪种默认值，首次登录必须立即改。把 admin / octop 暴露在公网等于开门揖盗，扫段脚本十分钟就能撞进来。Octop 的密码策略是至少 8 位且同时含字母与数字，弱密码或常见密码会被应用拒绝并回退到随机密码。

加固清单不止改密码：

  • 工具审批与 shell 护栏：风险工具和 shell 命令需要显式审批，护栏规则在 ~/.octop/security/tool_guard/ 下可编辑。生产环境务必开启，别让 AI 替你执行 rm -rf 这类命令。
  • PII 脱敏：敏感数据在出站前被脱敏，这是本地优先设计的一部分，确认它处于开启状态。
  • 暴露面收敛：如果只在自己机器用，octop run --host 127.0.0.1 就够了，不要为了「方便」监听 0.0.0.0 再裸奔公网。要对外，请走反向代理加 TLS，不要用明文 HTTP 直接扛公网流量。
  • 多用户隔离：管理员建成员账号，JWT 权限隔离，每人独立记忆、工作区与专家配置。别图省事全家共用 admin。

安全是 Octop 的设计卖点（本地优先可离线、工具审批、shell 护栏、PII 脱敏），但卖点不会自动生效，得你亲手打开。为什么强调工具审批？因为 Octop 能调 shell、能读写文件、能连外部系统，一旦被诱导执行危险命令，影响的是你整台机器。护栏规则放在 ~/.octop/security/tool_guard/，你可以按团队习惯写允许与拒绝清单，把高风险命令拦在门外。宁可多一次审批，别少一次兜底。

五、接入模型：OpenAI 兼容、Ollama 与近 20 家供应商

Octop 支持 OpenAI 兼容接口、DashScope（通义千问）、Ollama 本地模型，以及其它预设供应商，README 口径是「近 20 家」。配置方式有两种：在 Web 控制台按 agent 配，或用 CLI。先看一下已支持的供应商与模型解析：

bash
# 查看 LLM 供应商与模型解析
octop models
octop provider list

Ollama 本地模型的接法：在 Ollama 侧起好服务，把地址填进 Octop 的供应商配置即可，具体字段 README 没有逐条列出，以官方文档为准。OpenAI 兼容接口只要填 base_url 与 key 就能用，方便接各家兼容网关。关键点在于按 agent 分 key、最小权限：不要把一个全权限通用 key 塞给所有 agent，一旦泄露就是全线崩盘。README 没有写出每家供应商的确切字段名，因此 key 与端点填法以官方文档为准。

选模型的基本判断：日常对话与写作用通用大模型，代码生成用代码向模型，隐私数据走 Ollama 本地模型不出口。需要把 Octop 接进既有 Harness 技术栈的同学，可参考 Harness 技术栈资源。一个实用建议：把贵、把强的模型留给复杂任务，把本地 Ollama 小模型留给高频、可批量的简单活。这样既能控成本，又能保证隐私数据不出口。供应商 key 也建议按环境分：生产用受限 key，实验用临时 key，密钥泄露时影响面更小。

六、配专家与连接器、接 IM 通道

Octop 的差异化在专家库与连接器。专家库在启动时扫描 infra/agents/experts/library/，内置 16 种 MBTI 人格模板，也能自定义 system prompt；给每个 agent 挑专家或人格，就能让不同任务切不同「角色」。连接器（Connectors）走 OAuth 加 MCP 网关，覆盖腾讯文档、腾讯云 OpenAPI、新闻热搜等，把外部资源边界扩出去。

IM 通道让 Octop 进群干活。支持的通道与凭据如下（来自 README）：

通道所需凭据
飞书 FeishuApp ID、App Secret
钉钉 DingTalkApp Key、App Secret
QQBot AppID、Token
DiscordBot Token
企业微信 WeComCorp ID、Agent Secret
Web 控制台默认开启

安装与查看通道用 CLI：

bash
# 查看已装通道
octop channel list

# 安装通道
octop channel install

接 IM 最常见的坑是回调配置：飞书、企微这类需要公网回调的通道，务必核对 App Secret、回调 URL 与出口 IP，错一个就收不到消息。QQ、Discord 相对简单，填 token 即可。MCP 扩展怎么写、连接器 OAuth 怎么授权，README 没有给逐字步骤，以官方文档为准。

七、生产化与运维：备份、切换 PostgreSQL、升级

真要上生产，Docker Compose 是 README 明确推荐的形态。数据全在 ~/.octop/，目录里有 config.json（进程配置）、octop.db（SQLite，存用户、agent、通道、定时任务）、secrets/（JWT 密钥与通道 token）、agents/<agent_id>/（每个 agent 的工作区）、security/tool_guard/（shell 命令黑白名单）、logs/、venv/、bin/octop。

切换到 PostgreSQL：在 config.json 设 database 段，或用 OCTOP_DATABASE_* 环境变量，或首次运行向导里填。注意 README 明确：用 PostgreSQL 时，agent 记忆默认复用同一个 DSN（每个 agent 独立 schema）；如果想保留文件式记忆，要在 agent 配置里设 "memory": { "backend": { "type": "sqlite" } }。

备份与升级：

bash
# 导出 / 恢复备份
octop backup

# 升级：只替换 wheel / 二进制，~/.octop/ 下的数据库、工作区、密钥、config.json 都保留
octop update

octop update 升级后，schema 会在下次启动时自动迁移；只有向导提示要做迁移时才跑 octop init。跨大版本升级前一定先 octop backup。备份别只压一个 tar 就完事。~/.octop/ 里 secrets/ 存着 JWT 密钥和通道 token，agents/ 存着每个 agent 的工作区与记忆，这两块丢了等于重来。建议把备份目录单独存一份到异地或对象存储，并记下当前版本号，升级前再补一次，确保能回滚。下面是第 2 张表，把高频踩坑一次性列清。

坑现象解法
默认密码未改admin / octop 暴露在公网被扫首次登录立即改；强密码策略要求至少 8 位且含字母与数字
端口未加固8088 裸奔公网、无 TLS反向代理加 TLS，或仅监听内网；用 octop run --host 127.0.0.1
SQLite 并发上限多人同时写出现锁等待、卡顿切 PostgreSQL：在 config.json 设 database 或 OCTOP_DATABASE_*
IM 通道回调错飞书 / 企微收不到消息核对 App Secret、回调 URL 与出口 IP；以官方文档为准
模型 key 权限过大一个全权限 key 泄露拖垮全部按 agent 分 key、最小权限；用 octop provider 隔离
工作区迁移遗漏换机后记忆 / 专家丢失整目录搬 ~/.octop/，含 secrets 与 agents；先 octop backup

上线前 Checklist

  • 已改默认 admin 密码（至少 8 位，字母加数字）
  • 公网暴露已加 TLS 反向代理，或仅监听 127.0.0.1
  • 已开启工具审批与 shell 护栏（~/.octop/security/tool_guard/）
  • 已开启 PII 脱敏
  • 模型 key 按 agent 最小权限分配，无全权限通用 key
  • 已选定数据库后端（SQLite 单机 / PostgreSQL 多人）
  • 已配置 IM 通道回调与出口白名单
  • 已做首次 octop backup，~/.octop/ 目录已归档
  • 已注册系统服务 octop service start（或 Docker 自启）
  • 升级前先 octop backup，再用 octop update

常见问题

Q1：我到底该不该自托管 Octop？ A1：数据敏感、家庭共享、一人公司且愿意管服务器，就来自托管；只想用 AI、不想运维，去用云端助手更省心。判断标准只有一条：你愿不愿意为「数据在自己手里」付运维成本。

Q2：最低硬件要求是多少？ A2：README 没有给出固定核数，只写「现代多核 CPU、数 GB 内存给进程与模型或向量缓存、足够磁盘给数据库与工作区」。安装器会用 uv 在 ~/.octop/ 内建 Python 3.12+ 隔离环境，无需系统预装 Python。别拿低配机当生产。

Q3：默认账号密码是什么，必须改吗？ A3：默认管理员账号为 admin，默认密码官方 README 未写死，第三方评测口径为 octop（Docker 初始化则生成随机密码写入 credential.txt）；无论哪种，首次登录必须立即改。密码策略要求至少 8 位且同时含字母与数字，弱密码会被拒绝并回退随机密码。暴露在公网不改等于开门。

Q4：SQLite 够用吗，什么时候要切 PostgreSQL？ A4：单机、少人、低频够用。多人同时写出现锁等待或卡顿，就切 PostgreSQL：在 config.json 设 database 段或用 OCTOP_DATABASE_* 环境变量。注意 PostgreSQL 下 agent 记忆默认复用同 DSN，要保留文件式记忆需在 agent 配置里另设。

Q5：升级会丢数据吗？ A5：不会。octop update 只替换 wheel 或二进制，~/.octop/ 下的数据库、工作区、密钥、config.json 都保留，schema 下次启动自动迁移。但跨大版本升级前，一定先 octop backup 再升。

参考来源

  • Octop 官方 README（安装命令、端口、路径、供应商与通道凭据逐字取自）：TencentCloud/Octop
  • Octop 1.0 GA 与腾讯云 Lighthouse / CVM 官方镜像市场一条命令部署：腾讯云官方公众号（2026-09-17）
  • Harness 技术栈（harness-agent / harness-gateway / harness-memory / harness-browser）：README 相关项目一节

本文由 AI 辅助生成，经人工审核编辑。最后更新：2026-09-17

常见问题

我到底该不该自托管 Octop？
数据敏感、家庭共享、一人公司且愿意管服务器，就来自托管；只想用 AI、不想运维，去用云端助手更省心。判断标准只有一条：你愿不愿意为「数据在自己手里」付运维成本。
最低硬件要求是多少？
README 没有给出固定核数，只写「现代多核 CPU、数 GB 内存给进程与模型或向量缓存、足够磁盘给数据库与工作区」。安装器会用 uv 在 `~/.octop/` 内建 Python 3.12+ 隔离环境，无需系统预装 Python。别拿低配机当生产。
默认账号密码是什么，必须改吗？
默认管理员账号为 `admin`，默认密码官方 README 未写死，第三方评测口径为 `octop`（Docker 初始化则生成随机密码写入 `credential.txt`）；无论哪种，首次登录必须立即改。密码策略要求至少 8 位且同时含字母与数字，弱密码会被拒绝并回退随机密码。暴露在公网不改等于开门。
SQLite 够用吗，什么时候要切 PostgreSQL？
单机、少人、低频够用。多人同时写出现锁等待或卡顿，就切 PostgreSQL：在 `config.json` 设 `database` 段或用 `OCTOP_DATABASE_*` 环境变量。注意 PostgreSQL 下 agent 记忆默认复用同 DSN，要保留文件式记忆需在 agent 配置里另设。
升级会丢数据吗？
不会。`octop update` 只替换 wheel 或二进制，`~/.octop/` 下的数据库、工作区、密钥、config.json 都保留，schema 下次启动自动迁移。但跨大版本升级前，一定先 `octop backup` 再升。

相关文章

实战 SOP

书生-S2 接入实操：从免费 API 到科学长程任务

书生-S2 接入实操 SOP：对个人与小团队最现实的是免费 API（chat.intern-ai.org.cn 在线体验、internlm.intern-ai.org.cn/api/strategy 领额度），有算力机构可走 HuggingFace internlm/Intern-S2-397B 权重推理。文章给出三种接入对照表、免费 API 最小可运行 Python 调用、HF 推理骨架、科学长程任务两套可直接改的 prompt 模板（分子结合剂设计、材料结构生成），以及 Memory Decoder 记忆模块挂载说明与十项踩坑（免费额度限速、397B 显存爆炸、长上下文截断、Preview 版 2026-10-31 下线迁移等）。结论：个人零成本先走免费 API，别一上来就想着本地部署 397B。

2026年9月17日11 分钟阅读
实战 SOP

diagram-design 接入 Claude Code 的实操 SOP

把 diagram-design 这套图表技能包接进日常编码工作流的实操 SOP，命令逐字取自项目官方 README。分七步走：先交代它解决什么问题与不解决什么；再给各宿主安装与更新命令对照表（Claude Code 的 /plugin marketplace add 与 /plugin install、Codex 的 codex plugin marketplace add 与 plugin add、GitHub Copilot 的 copilot plugin 系列、Factory Droid 的 droid plugin 系列带 --scope user、Pi 的 pi install 加 /reload、Kiro 的子目录 URL 导入、OpenCode 的目录复制或软链）；然后是首次运行 gate（默认皮肤未改会停下来问你要不要 onboarding）与品牌 onboarding（读站点抽色抽字、映射语义 token、WCAG AA 对比度校验、保真回执）；接着是出图与自检，含三条可直接抄的自然语言示例与官方那六条算跑通了的判据，以及 self_check.py 打印 OK 才算过；导出与导入一节讲清四个旋钮与只导出图本身这个边界，还有 fidelity ledger 长什么样；多客户品牌隔离用命名 profile 加 .diagram-design 标记文件实现。第七节是十项踩坑速查，条条写清现象与原因，例如 Claude Code 对第三方 marketplace 默认关闭自动更新、Factory Droid 按 commit 跟踪而不认 manifest 版本号、Pi 没有自动刷新要手动 pi update --extensions、Kiro 是复制不是链接、OpenCode 复制式安装不会自动更新、旧版 npx skills add 装的独立副本不会跟随 Codex marketplace、自定义 style-guide.md 会被包更新覆盖、PNG 导出首次缺 Playwright 与 Chromium、误以为导出包含全版式、以及动效 HTML 截图会截到中间帧。核心判断：这套技能包真正的门槛不在安装，而在版本更新路径与产出物边界 —— 官方为每个宿主分别写更新命令这件事本身就是信号，跨宿主技能包的分发与升级至今没有统一答案。

2026年9月15日11 分钟阅读
实战 SOP

LingBot-World 2.0 本地小模型部署实操 SOP

把 LingBot-World 2.0 的 1.3B causal-fast 在本地跑起来的实操 SOP：环境与依赖（torch 2.4.0 以上、flash-attn 等，命令逐字取自官方 requirements.txt）到权重下载（1.3B 包只含 DiT 权重，T5、VAE、tokenizer 与 14B 共享，必须用 assets_dir 指向 14B 目录，否则起不来），再到跑通第一段（torchrun 或官方 run_fast.sh），以及参数调优（frame_num 须为 4n+1、local_attn_size 18、sink_size 6、chunk_size、base_seed、save_dir），最后落到生产化与部署路径（官方不开源部署代码，参考 SGLang cookbook 或 NVIDIA flashdreams），收尾八条踩坑与十项上线 checklist。关键踩坑：硬件门槛口径三重分歧（README 示例 1.3B 四卡、run_fast.sh 参考二卡、媒体称消费级单卡实时），以代码仓为准、最低可复现二卡、单卡实时标注未确认；ulysses_size 必须整除注意力头数（1.3B 为 12、14B 为 40）并与 nproc_per_node 相等；causal_fast（每 chunk 4 步、无 CFG）与 causal_pretrain（每 chunk 40 步、有 CFG）的取舍；许可证 CC BY-NC-SA 4.0 非商用，产品化前须先确认授权。

2026年9月14日11 分钟阅读