读 Octop 源码(3):配置、目录布局,和那个「先不建库」的判定
第 1 篇写启动链的时候,有个分叉我没敢展开:
if should_defer_control_plane_db(config, self.paths):
self._started = True
self._emit_wizard_password(user_count=0)
return
OctopServer.start() 跑到这里就 return 了——进程立起来了,但运行时树一个都没建。
当时只说"这是为了首次运行弹选数据库的向导"。这篇把这件事讲完:判定条件是什么、向导阶段怎么授权、以及配置和目录布局这两个看起来最无聊的东西,其实藏着不少设计。
版本锚点:本文基于
octopv1.0.2(commitdd9dce4)。config.py633 行,infra/setup/3,331 行(含tls/1,038 行、self_update.py1,181 行)。
环境准备
这篇的验证对象是"配置文件和目录",都在磁盘上,直接看。
第一,看实际配置文件长什么样。 注意脱敏——这里面有 require_setup_password 这类字段:
cd ~/WorkBuddy/Claw/octop
python3 -c "
import json
d = json.load(open('.home/.octop/config.json'))
print(json.dumps(d, indent=2, ensure_ascii=False)[:1200])
"
我这台机器的实际内容(省略密钥字段):
{
"bind_host": "127.0.0.1",
"port": 8088,
"log_level": "info",
"access_token_ttl_seconds": <已脱敏>,
"login_max_attempts": 5,
"login_lockout_seconds": 900,
"default_timezone": "Asia/Shanghai",
"enable_dashboard": true,
"enable_api_docs": false,
"history_v2_enabled": false,
"database": {
"driver": "sqlite",
"sqlite_path": "octop.db",
"host": "127.0.0.1", "port": 5432,
"database": "octop", "user": "octop"
},
"tls": { "enabled": false, "mode": "", "cert_file": "", "key_file": "",
"issued_at": "", "expires_at": "", "acme_staging": false, "http_port": 80 }
}
注意 database 段里 PostgreSQL 的 host/port/user 是带着默认值的,即使你用的是 SQLite。这不是浪费——它让"以后切 PG"不用再猜字段名。
第二,看数据目录的布局。
ls -1 .home/.octop/
# agents browser-profiles config.json embedding_models logs
# memory-slim-control.json octop.db octop.db-shm octop.db-wal
# plugins security workspaces
十一个条目,每个都有明确归属。这份清单本身就是个契约——第 2 篇讲的"三层存储"在这里能一眼对上:octop.db 是控制面,agents/<id>/ 里才是检查点和记忆。
流程
一、配置是五层嵌套的 dataclass,不是一个 dict
config.py 633 行,但结构极其规整——一个顶层 dataclass 套四个子 dataclass:
@dataclass
class DatabaseConfig:
driver: str = "sqlite"
sqlite_path: str = "octop.db"
host: str = "127.0.0.1"
port: int = 5432
database: str = "octop"
user: str = "octop"
password: str | None = None
url: str | None = None # verbatim OCTOP_DATABASE_URL when set
@dataclass
class TlsConfig:
enabled: bool = False
mode: str = ""
domains: list[str] = field(default_factory=list)
cert_file: str = ""
key_file: str = ""
issued_at: str = ""
expires_at: str = ""
acme_staging: bool = False
http_port: int = 80
@dataclass
class BackupConfig:
auto_enabled: bool = False
schedule: str = "cron:0 4 * * *"
retention_count: int = 7
include_config: bool = True
include_workspaces: bool = True
include_skill_packages: bool = True
include_plugins: bool = True
include_knowledge: bool = True
include_chats: bool = False # ← 默认不备对话
@dataclass
class OctopConfig:
bind_host: str = "127.0.0.1"
port: int = 8088
log_level: str = "info"
...
四个默认值值得单独看,因为默认值就是产品的态度:
bind_host = "127.0.0.1" —— 默认只听本地。想局域网访问必须显式改成 0.0.0.0。这是对的:一个装了 27 个插件、能读写文件、能控制浏览器的服务,默认暴露到局域网是灾难。
enable_api_docs = False —— API 文档默认关。这也是安全考量,Swagger 页面等于把 523 个端点的目录送给别人。
login_max_attempts = 5 / login_lockout_seconds = 900 —— 五次失败锁十五分钟。默认就有暴力破解防护。
BackupConfig.include_chats = False —— 备份默认不含对话内容。这个默认值很值得玩味:备份主要是为了"坏了能起来",而对话是隐私。默认不备,需要的话自己开。
二、目录布局被当成 API 来对待
PathLayout 在 infra/utils/paths.py,全是 property:
@property
def db(self) -> Path: ...
@property
def logs_dir(self) -> Path: ...
@property
def config(self) -> Path: ...
@property
def users_dir(self) -> Path: ...
@property
def agents_dir(self) -> Path: ...
@property
def expert_market_dir(self) -> Path: ...
@property
def published_experts_dir(self) -> Path: ...
@property
def skill_packages_dir(self) -> Path: ...
@property
def knowledge_dir(self) -> Path: ...
@property
def plugins_dir(self) -> Path: ...
没有一个方法接收"根目录"参数,全部挂在实例上——因为根目录在构造时定了,之后不该变。
这件事看着平淡,但它是"可迁移"的前提:OCTOP_HOME 指到哪,整套数据就跟到哪。第 5 篇讲的那个 ensure_agent_workspace(agent_id) 之所以只按 agent_id 拼路径,就是因为根目录已经在 PathLayout 里了。
目录布局是 API 的一部分。 用户会 cp -a ~/.octop /backup/、会 scp 到另一台机器、会把 agents/<id>/ 单独挂到 NFS 上。这些操作一旦被代码假设破坏,用户就失去了对自己数据的控制权。所以路径定义集中在一个文件里、全部 readonly property、没有一个地方手拼字符串——这是很克制的做法。
顺带一个实测发现:workspaces/ 和 agents/ 是两个并列目录。前者是老的全局 workspace,后者是按 Agent 分的。第 5 篇里 resolve_workspace_dir() 那段"legacy / incomplete row"的兼容分支就是为这个并存留的。
三、「先不建库」的判定,有效逻辑只有 5 行
回到开头那个分叉。should_defer_control_plane_db() 在 infra/db/factory.py 里,有效逻辑只有 5 行:
def should_defer_control_plane_db(config: OctopConfig, paths: PathLayout) -> bool:
"""True when first-run setup should delay opening the control-plane DB.
Defer only for greenfield SQLite installs with no existing DB file and no
``OCTOP_DATABASE_*`` / PostgreSQL configuration. Password verification and
early wizard steps then run without a pool.
"""
if config.database.is_postgresql:
return False
if database_env_configured():
return False
return not resolve_sqlite_db_path(config, paths).exists()
三个条件全中才延迟:不是 PG、没有数据库环境变量、SQLite 文件不存在。
这三个条件的逻辑是一致的:只有在"用户什么都没说"的时候才去问。
- 配了 PostgreSQL → 用户已经明确选了后端,不用问。
- 设了
OCTOP_DATABASE_*环境变量 → 同上。而且这点很关键:容器部署几乎全靠环境变量,这时候不该弹向导。 - SQLite 文件已存在 → 不是首次运行。
换句话说,向导只在"真空环境"里出现。 这个判定写得比大多数"首次运行检测"都准——很多项目用"配置文件不存在"来判断,结果环境变量配置的部署也会被弹一遍向导。
那个 _emit_wizard_password(user_count=0) 做的事是:生成一次性管理员密码,打到终端和日志里。因为这时候连用户表都还没有,不能靠账号密码登录。
四、向导阶段怎么授权:一个 5 分钟的一次性凭证
这里有个真问题:首次运行的向导要让人配置数据库、设管理员密码,可这时没有数据库、没有用户、没有 JWT 密钥——凭什么授权?
如果什么都不校验,任何人打开 http://ip:8088 都能抢先完成初始化(经典的"未授权初始化"漏洞)。
WizardTokenStore 在 infra/setup/wizard_tokens.py,67 行,思路很直接:
self.wizard_tokens = WizardTokenStore(ttl_seconds=300)
5 分钟 TTL 的一次性令牌。 服务启动时生成,打到终端(只有能看服务器输出的人拿得到),向导的每一步都要带上它。
这个设计解决了两件事:
- 证明"你在机器旁边":只有能看到进程 stdout 的人才有这个 token,等价于"物理接触"。
- 自动过期:5 分钟没走完向导就失效,防止 token 残留在日志里被后来者捡到。
配套还有 password_file.py(81 行)——把初始密码写到文件而不是只打日志,方便容器场景用 cat 取。
这类"引导期的最小授权"是自托管项目普遍处理不好的一块。 常见做法有三种:完全不管(危险)、要求先手工改配置文件(体验差)、或者生成 token(Octop 选的这个)。第三种是唯一兼顾安全和零配置的。
五、TLS:双监听和那个被迫的 workers=1
infra/setup/tls/ 1,038 行,做 Let’s Encrypt 自动签发。第 1 篇提过 launch.py 里有个 plan.dual_listeners 分叉,这里说清楚它是什么。
ACME 的 HTTP-01 验证要求:申请证书时,http://yourdomain/.well-known/acme-challenge/<token> 必须能返回指定内容。也就是说在还没有证书的时候,必须先开一个 80 端口的 HTTP 服务。
所以 build_listen_plan() 会产出三种结果,其中一种就是"双监听":
if plan.dual_listeners:
https_config = uvicorn.Config(app, host=plan.bind_host, port=plan.https_port,
workers=worker_count, ssl_certfile=..., ssl_keyfile=...)
companion = build_http_companion_app(https_port=plan.https_port)
http_config = uvicorn.Config(companion, host=plan.bind_host, port=plan.http_port,
workers=1, reload=False)
servers.append(uvicorn.Server(https_config))
servers.append(uvicorn.Server(http_config))
注意 companion 是个独立的迷你 ASGI 应用,不是主 app。它只干两件事:响应 ACME challenge、把其它请求 301 到 https。这个隔离很好——80 端口上不暴露任何业务逻辑。
然后是那个被迫的妥协:
worker_count = 1 if plan.dual_listeners or reload else workers
if plan.dual_listeners and (reload or workers > 1):
logger.warning("TLS dual-port mode forces workers=1 and disables reload")
开 TLS 双监听就强制单 worker、禁用 reload。 原因是两个 uvicorn Server 跑在同一个事件循环里,多 worker 会让进程 fork 出多份、每个都想绑同一个端口,直接冲突。
这个约束在第 1 篇的 asyncio.gather(*(_serve(s) for s in servers)) 那里能看出来——两个 server 是在同一进程的两个协程,不是两个进程。
和第 2 篇的 BEGIN IMMEDIATE 一样,这也是一条"只在特定部署形态下才暴露"的约束:本地开发永远单 worker,上线开 TLS 才发现 workers 参数被吃掉了。
六、self_update.py 1,181 行:能自己升级自己
infra/setup/ 里最大的是 self_update.py,比 service.py(963 行,管 launchd/systemd 安装)还大。
"""Self-upgrade helpers shared by CLI and HTTP update API."""
CLI 和 HTTP 更新 API 共用同一套升级逻辑。 也就是说你可以在网页上点"检查更新 → 立即升级",它会:备份 → pip 装新版 → 重启服务 → 健康检查。
1,181 行里大部分是防御:装之前检查磁盘空间、装之后校验版本、失败回滚、重启期间保持连接、清理临时文件。这类代码写不短,因为每一步都可能失败,而失败在"升级"这个场景里代价极高——升完起不来,用户的服务就没了。
我没有细读这个文件,但从体量能推断出它承担的责任:自托管产品的"一键升级"是个运维系统,不是一行 pip install -U。
总结
配置和引导这一层,四句话:
- 配置是五层嵌套 dataclass,默认值就是安全策略。
bind_host=127.0.0.1(默认只听本地)、enable_api_docs=False、登录 5 次失败锁 15 分钟、备份默认不含对话。没一个是随便填的。 - 目录布局被当 API 对待。
PathLayout全是 readonly property,没有任何地方手拼路径。因为用户会cp -a、会scp、会单独挂agents/到 NFS——路径一旦被代码假设锁死,用户就失去对自己数据的控制权。 - “先不建库"的判定只有 12 行,逻辑是"只在真空环境里才问”。 不是 PG、没有
OCTOP_DATABASE_*、SQLite 文件不存在,三条全中才延迟。用"配置文件不存在"来判断首次运行是个常见错误,容器部署会被误弹向导。 - 向导期的授权靠 5 分钟 TTL 的一次性令牌。 生成后打到终端,只有能看到服务器输出的人拿得到,等价于"物理接触"。这是自托管项目处理"引导期最小授权"的合理方案。
还有一个结构性的观察:这篇里所有"坑"(TLS 强制单 worker、legacy workspace 兼容)都是只在特定部署形态下才暴露的。这和前面几篇一样——单进程 + 多形态部署,让很多约束藏在分支里。读这个项目,光看主路径是不够的,得把 if 的分支都翻一遍。
下一篇按编号写 Agent 中间件链:HarnessAgent 编译时挂的那 9 个中间件,每个解决一个具体问题,以及为什么 OctopUiOffload 必须放最内层。
参考链接
- 仓库:https://github.com/TencentCloud/Octop(MIT)
- 本文主读文件:
src/octop/config.py(633 行)src/octop/infra/utils/paths.py(PathLayout)src/octop/infra/db/factory.py(44 行,含延迟判定)src/octop/infra/setup/wizard_tokens.py(67 行)src/octop/infra/setup/tls/(1,038 行)src/octop/infra/setup/self_update.py(1,181 行)
- 前一篇:(2)三层存储和一个 2100 行的迁移器 · (1)先摊开地图
