读 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 了——进程立起来了,但运行时树一个都没建。

当时只说"这是为了首次运行弹选数据库的向导"。这篇把这件事讲完:判定条件是什么、向导阶段怎么授权、以及配置和目录布局这两个看起来最无聊的东西,其实藏着不少设计。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4)。config.py 633 行,infra/setup/ 3,331 行(含 tls/ 1,038 行、self_update.py 1,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 的一次性令牌。 服务启动时生成,打到终端(只有能看服务器输出的人拿得到),向导的每一步都要带上它。

这个设计解决了两件事:

  1. 证明"你在机器旁边":只有能看到进程 stdout 的人才有这个 token,等价于"物理接触"。
  2. 自动过期: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。

总结

配置和引导这一层,四句话:

  1. 配置是五层嵌套 dataclass,默认值就是安全策略。 bind_host=127.0.0.1(默认只听本地)、enable_api_docs=False、登录 5 次失败锁 15 分钟、备份默认不含对话。没一个是随便填的。
  2. 目录布局被当 API 对待。 PathLayout 全是 readonly property,没有任何地方手拼路径。因为用户会 cp -a、会 scp、会单独挂 agents/ 到 NFS——路径一旦被代码假设锁死,用户就失去对自己数据的控制权。
  3. “先不建库"的判定只有 12 行,逻辑是"只在真空环境里才问”。 不是 PG、没有 OCTOP_DATABASE_*、SQLite 文件不存在,三条全中才延迟。用"配置文件不存在"来判断首次运行是个常见错误,容器部署会被误弹向导。
  4. 向导期的授权靠 5 分钟 TTL 的一次性令牌。 生成后打到终端,只有能看到服务器输出的人拿得到,等价于"物理接触"。这是自托管项目处理"引导期最小授权"的合理方案。

还有一个结构性的观察:这篇里所有"坑"(TLS 强制单 worker、legacy workspace 兼容)都是只在特定部署形态下才暴露的。这和前面几篇一样——单进程 + 多形态部署,让很多约束藏在分支里。读这个项目,光看主路径是不够的,得把 if 的分支都翻一遍。

下一篇按编号写 Agent 中间件链:HarnessAgent 编译时挂的那 9 个中间件,每个解决一个具体问题,以及为什么 OctopUiOffload 必须放最内层。

参考链接