Archon 数据库完整指南SQLite 与 PostgreSQL 双后端架构、18 张核心表与自动化 Schema 收敛【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本篇是 Archon 开源仓库的数据库参考指南覆盖从「零配置 SQLite 单机使用」到「云端 PostgreSQL 多容器部署」的完整路径。你将掌握DATABASE_URL驱动的后端自动选择机制、启动时幂等 Schema 收敛的实现原理、remote_agent_前缀下 18 张业务表的职责与关键约束以及从000_combined.sql到023的迁移演进脉络并学会用健康检查与命令行工具验证数据库状态。双后端架构一个环境变量决定一切Archon 支持两种数据库后端选择逻辑完全由环境变量DATABASE_URL驱动SQLite默认后端零配置适合单用户 CLI 使用PostgreSQL可选后端用于云端与高级部署Supabase、Neon 等托管服务或 Docker Compose 本地容器。选择逻辑位于 packages/core/src/db/connection.ts 的getDatabase()当process.env.DATABASE_URL存在时实例化PostgresAdapter否则实例化SqliteAdapter并打开~/.archon/archon.db。连接以单例形式缓存getDialect()会随后端返回对应的 SQL 方言助手如 UUID 生成、JSON 合并、日期计算上层业务代码无需关心底层是哪种数据库。从源码结构还可以看到一处贴心设计当检测到在 Docker 环境ARCHON_DOCKERtrue运行却未设置DATABASE_URL时连接层会打出db.docker_using_sqlite警告提示你可能启动了with-db的 PostgreSQL 容器但应用仍在静默使用 SQLite——这是最容易踩的坑值得部署时留意。SQLite默认零配置即用什么都不用做。只要.env中不设置DATABASE_URL应用会自动在~/.archon/archon.db创建 SQLite 数据库首次运行时自动建好父目录首次启动时初始化 Schema所有读写操作都落在这个文件上。对应实现见 packages/core/src/db/adapters/sqlite.ts 的SqliteAdapter构造器它初始化时还做了三件对并发至关重要的 PRAGMA 设置PRAGMA journal_mode WAL启用 WAL 模式提升并发读写性能PRAGMA busy_timeout 5000忙锁重试 5 秒避免并行工作流触发SQLITE_BUSYPRAGMA foreign_keys ON启用外键约束。优点零配置、无需外部数据库、单用户 CLI 场景开箱即用。缺点不适合多容器部署没有网络访问能力CLI 与 server 无法跨主机共享数据库。SQLite 的 Schema 初始化策略SQLite 没有 PostgreSQL 的CREATE TABLE IF NOT EXISTS全量幂等便利对已存在表CREATE是空操作新列不会自动补上。因此SqliteAdapter的初始化分为两步见 sqlite.ts 中initSchemacreateSchema()用带IF NOT EXISTS的 DDL 创建全部表与索引migrateColumns()用PRAGMA table_info(...)探测旧库缺失的列逐个ALTER TABLE ADD COLUMN补齐如users.role、codebases.default_branch/kind、conversations.user_id/title/deleted_at/hidden、workflow_runs.parent_run_id/adopted_from_run_id/output_root/outcome等并为新增列补建索引与触发器。值得注意的细节SQLite 端对remote_agent_workflow_events.event_order的单调递增赋值是通过AFTER INSERT触发器实现的PostgreSQL 侧则用序列且索引/触发器的创建被刻意放在migrateColumns()中而非createSchema()——因为老库在列被ALTER TABLE补上之前对缺失列建索引会直接中止整个 DDL 块。此外migrateColumns()中每个表各自的迁移失败会被单独抑制allApplied标记一次坏的ALTER不会中止启动同时避免把「未完整应用」的库错误盖上当前版本号。远程 PostgreSQLSupabase、Neon 等托管服务在.env中设置远程连接串即可DATABASE_URLpostgresql://user:passwordhost:5432/dbname无需手动执行迁移。启动时Postgres 适配器会在一个咨询锁advisory lock事务内应用打包的 migrations/000_combined.sql。该 SQL 完全幂等CREATE TABLE IF NOT EXISTS、ADD COLUMN IF NOT EXISTS、CREATE INDEX IF NOT EXISTS因此全新安装与版本升级都会自动收敛到最新 Schema——包括后续版本新增的表和列。底层机制一次启动即完成的收敛实现细节见 packages/core/src/db/adapters/postgres.ts 的initSchema()通过SELECT pg_advisory_xact_lock(1796)串行化并发启动如两个应用容器同时指向全新数据库应用前先探测to_regclass(remote_agent_codebases)判断库是否已存在用于记录创建版本在事务内执行整份幂等 SQL随后写入/更新remote_agent_schema_version单行记录诊断用途写入失败仅告警不阻断每个query()与withTransaction()都会先await schemaInitPromise保证首个数据库操作不可能与初始化竞争Schema 提交后额外安装 Postgres 专属的pg_notify触发器见下文「实时事件推送」小节该步骤失败只会降级为轮询模式不会导致启动失败。getSchemaSQL()见 packages/core/src/db/bundled-schema.ts在源码构建时直接读取磁盘上的migrations/000_combined.sql二进制构建时使用bundled-schema.generated.ts内嵌的字符串——后者由scripts/generate-bundled-schema.ts生成保证分发版本自带完整 Schema。升级是「被验证」的不是「被假设」的CI 会执行如下校验把当前 Schema 应用到一个由Archon 历史上发布过的每一个不同 Schema 版本vintage构建的数据库之上再次应用以确认幂等性然后把结果与全新安装逐项对比——包括列、索引、列注释、约束与序列。你可以在任意 PostgreSQL 上自行复跑同一检查bun run check:schema-upgrades实现位于 scripts/check-schema-upgrades.ts它会遍历 git 标签中携带的每个不同历史 Schema 快照按 blob 去重例如 v0.3.0 到 v0.3.12 字节级相同只算一份对每个基线「先应用当前 Schema、再应用一遍、再与全新库 diff」任何一项不一致都会输出FAIL并给出退出码。失败处理若 Schema 应用失败权限不足、语法错误、网络问题进程会在首个数据库操作处中止底层 Postgres 错误以db.pg_schema_init_failed为键记录日志。本地 PostgreSQLDocker Composewith-dbProfile使用仓库根目录 docker-compose.yml 的with-dbprofile 可一键拉起本地 PostgreSQLdocker compose --profile with-db up -d然后在.env中设置连接串DATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agent其中postgres是 Compose 内的服务名remote_coding_agent是镜像初始化时创建的数据库名POSTGRES_DB。Compose 中 PostgreSQL 服务还暴露了127.0.0.1:5432端口方便本机psql直连。与远程 PostgreSQL 完全相同应用启动时自动收敛 Schema——全新安装与升级走同一条路径。原先docker compose up -d中docker-entrypoint-initdb.d挂载的migrations/000_combined.sql现在已冗余仅作为全新卷上的空操作no-op保留。注意Docker 部署下若忘了设置DATABASE_URL应用会退回 SQLite 并在日志中输出db.docker_using_sqlite警告数据库不会自动「切」到 Postgres 容器。验证数据库状态健康检查端点实现于 packages/server/src/index.ts 的/health/db路由内部执行SELECT 1curl http://localhost:3090/health/db # Expected: {status:ok,database:connected}失败时返回 HTTP 500 与{status:error,database:disconnected}。列出全部表PostgreSQLpsql $DATABASE_URL -c \dtSQLite可直接查看 Schema 版本记录sqlite3 ~/.archon/archon.db SELECT * FROM remote_agent_schema_version;remote_agent_schema_version是单行诊断表id 1记录「由哪个 Archon 构建创建」「最近一次由哪个构建应用 Schema」对排查「数据库是从哪个版本升上来的」非常有用。Schema 全景18 张remote_agent_表所有业务表统一以remote_agent_为前缀共 18 张。完整 DDL 见 migrations/000_combined.sqlSQLite 版本见 packages/core/src/db/adapters/sqlite.ts 的createSchema()。下面按职责分组逐表说明。仓库与项目1.remote_agent_codebases— 仓库元数据命令以 JSONB 存储{command_name: {path, description}}每个 codebase 的 AI 助手类型ai_assistant_type默认claude默认工作目录default_cwdkindrepo|folder默认repo区分 git 仓库项目与非 git 文件夹项目后者原地运行不走 worktree可空的已探测默认分支default_branch存在时作为工作区同步的分支上下文。8.remote_agent_codebase_env_vars— 项目级环境变量键值对作用域限定到单个 codebaseUNIQUE(codebase_id, key)执行时注入 Claude SDK 子进程环境源码注释merged into Options.env on Claude SDK callsWeb UI 的 Settings 面板管理CLI 用户通过.archon/config.yaml中的env:配置另有remote_agent_codebases.allow_env_keys布尔列控制是否放行。对话与消息2.remote_agent_conversations— 平台会话跟踪platform_typeplatform_conversation_id唯一约束同一平台会话只对应一行通过外键关联 codebaseAI 助手类型在创建时锁定可空user_id记录创建会话的首个用户first-user-wins同线程后续回复归属在workflow_run上而非这里deleted_at/hidden支撑软删除与隐藏。7.remote_agent_messages— 会话消息历史持久化用户与助手消息及时间戳支撑 Web UI 刷新后仍能恢复历史工具调用元数据名称、输入、耗时存于 JSONB可空user_id只出现在role user的行上助手行的该列为 NULL。3.remote_agent_sessions— AI 会话管理活跃会话标志每会话一个assistant_session_id提供恢复resume能力metadataJSONB 存命令上下文parent_session_id自引用 FK 构成会话谱系transition_reason/ended_reason记录会话流转与结束原因对应迁移 010、016。工作流执行与可观测性4.remote_agent_isolation_environments— Worktree 隔离按 issue/PR 跟踪 git worktree支持关联 issue 与 PR 间共享 worktreeworkflow_typeissue/pr/review/thread/taskworkflow_id标识工作可空created_by_user_id跨重新激活保留原始创建者ON CONFLICT DO UPDATE刻意不更新该列活跃状态唯一性由部分唯一索引unique_active_workflow仅status active保证。5.remote_agent_workflow_runs— 工作流执行追踪记录每个会话的活跃工作流status取pending/running/completed/failed/cancelled/paused同路径并发锁对同一working_path若已有pending/running/paused的活跃运行第二次派发会被自动取消并给出可操作提示超过 5 分钟的陈旧pending行视为孤儿忽略workflow:子运行共享父运行 checkout除非节点声明isolation: worktree因此路径锁排除祖先链与后代经parent_run_id子运行不会与自己的父运行竞争但兄弟运行之间不排除可空parent_run_id自引用 FKON DELETE SET NULL把workflow:子运行链接到产生它的父运行顶层运行为 NULL。使运行树可遍历findChildRuns/getRunAncestry支撑 abandon 级联与成本汇总adopted_from_run_id记录跨运行延续写一次恢复时不改写output_root是运行开始时解析的~/.archon/workspaces/project/目录使历史产物在 codebase 改名后依然可寻conversation_id在会话删除时级联对会话的硬DELETE会连带抹掉运行行并静默丢失其隔离环境的 live-run 清理 pin——因此软删除是唯一受支持的路径未来若实现硬删除必须先解决活跃运行的清理。6.remote_agent_workflow_events— 步骤级事件日志记录每次运行的步骤转换、产物与错误只存精简的 UI 相关事件详细日志在 JSONL 文件中支撑运行详情视图与调试在created_at上建索引idx_workflow_events_created_at供仪表盘事件轮询器做跨运行尾部读取。11.remote_agent_workflow_node_sessions— 跨重跑的节点级 provider 会话通过persist_session可选启用以(workflow_name, node_id, scope_key, provider)为主键scope_key通常是会话 UUID不设外键因此会话删除不会级联到这里——软删除 永不复用的 UUID 让残留无害未来硬删除需按scope_key自行清理与workflow_runs级联警示互为镜像。另有源码中可见的两张辅助表remote_agent_schema_version前述诊断用与remote_agent_workflow_run_node_sessions单次运行内部、按(workflow_run_id, node_id)主键、随运行级联、不通过 API 暴露的私有会话句柄。用户与身份9.remote_agent_users— Archon 内部用户身份每个人类或机器人跨平台一行任何 chat/forge 适配器首次见到即惰性创建display_name与email在充实成功前可空roleVARCHAR默认admin是为未来按资源做权限划分预留的身份接缝——当前所有人都是admin可见性保持开放member为保留值。10.remote_agent_user_identities— 平台到 Archon 用户的映射每个(platform, platform_user_id)一行——Slack U-id、Telegram chat id、Discord snowflake、GitHub login、Web 端 Better Auth 用户 id 等UNIQUE(platform, platform_user_id)在数据库层去重引用users.id时ON DELETE CASCADE删用户即删其身份映射与之相对四个业务表上的所有user_id外键都用ON DELETE SET NULL确保未来删除用户不会造成破坏性级联。12.remote_agent_user_github_tokens— 每用户 GitHub device-flow 令牌静态加密AES-256-GCM每 Archon 用户一行UNIQUE(user_id)随用户删除级联数值型github_user_id锚定 commit 的 no-reply 邮箱。13.remote_agent_user_provider_keys— 每用户 AI provider 凭据API Key 或 OAuth 订阅 blob静态加密AES-256-GCM使用同一个TOKEN_ENCRYPTION_KEY每(user_id, provider)一行随用户删除级联kind区分api_key与oauth执行时解析并注入用户运行/聊天的环境provider保存厂商规范凭据 idanthropic、openai、github-copilot以及 Pi 后端厂商——历史遗留的claude/codex/copilot行由启动时的幂等数据修复改名两者并存时厂商行胜出。14.remote_agent_user_ai_prefs— 每用户 AI 偏好个人模型层级、custom别名、默认助手与默认聊天模型不加密模型名不是秘密每用户一行UNIQUE(user_id)随用户删除级联tiers/aliases为 JSON-as-TEXT作为最高优先级层参与模型解析default_model钉住用户的直接聊天模型与default_provider原子写入仅当生效聊天 provider 匹配时应用工作流仍解析large层级解析遵循行为用户工作流运行用运行发起者聊天轮次用消息发送者会话创建者的行仅在无法解析发送者身份时作为兜底编辑入口控制台 Just me 作用域、archon ai … --scope user、/api/auth/me/ai-prefs*。15–18.remote_agent_auth_user/remote_agent_auth_session/remote_agent_auth_account/remote_agent_auth_verification— Better Auth 表可选 Web 登录仅 PostgreSQL。Postgres 上由幂等 Schema 应用总是创建但仅在启用 Web 认证DATABASE_URLBETTER_AUTH_SECRET时才写入数据归 Better Auth 所有并塑形文本 id、camelCase 列Archon 从不直接查询它们——一个 session 经由user_identities(web, betterAuthUserId)映射到规范的users行。PostgreSQL 专属实时事件推送在 PostgreSQL 上remote_agent_workflow_events存在一个AFTER INSERT触发器archon_workflow_event_notify调用pg_notify(archon_dashboard_event, …)使得进程外启动的运行archonCLI /--detach也能实时流式进入控制台SQLite 上则由轮询器按间隔拾取。该触发器仅限 Postgres 且尽力而为——角色无CREATE TRIGGER权限时降级为纯轮询不会导致启动失败对应 postgres.ts 中installNotifyTrigger()的独立事务与告警日志db.postgres_notify_trigger_install_failed。迁移清单与版本演进migrations/目录下的迁移文件按时间线演进SQLite 端则由createSchema()migrateColumns()内联完成等效变更迁移说明000_combined.sql合并后的初始 Schema全新安装用这份001_initial_schema.sql初始 Schemacodebases、conversations、sessions002_command_templates.sql命令模板表003_add_worktree.sql添加 worktree 列004_worktree_sharing.sqlworktree 共享支持005_isolation_abstraction.sql隔离抽象层006_isolation_environments.sql隔离环境表007_drop_legacy_columns.sql删除遗留 worktree 列008_workflow_runs.sql工作流运行表009_workflow_last_activity.sql工作流最近活动追踪010_immutable_sessions.sql不可变会话模型011_partial_unique_constraint.sql部分唯一约束012_workflow_events.sql工作流事件表013_conversation_titles.sql会话标题014_message_history.sql消息历史表015_background_dispatch.sql后台派发支持016_session_ended_reason.sql会话结束原因字段017_drop_command_templates.sql删除命令模板表018_fix_workflow_status_default.sql修复工作流状态默认值019_workflow_resume_path.sql工作流恢复路径支持020_codebase_env_vars.sql项目级环境变量021_add_allow_env_keys_to_codebases.sql每 codebase 的放行 env 键022_workflow_node_sessions.sql每节点 provider 会话持久化023_add_default_branch_to_codebases.sqlcodebases 上探测的默认分支几点说明均以当前仓库实际内容为准早期通过002引入、017移除的remote_agent_command_templates已被文件化命令.archon/commands取代——000_combined.sql 开头也以DROP TABLE IF EXISTS清理遗留对象remote_agent_codebases.kind列、remote_agent_users.role列以及四张remote_agent_auth_*Better Auth 表是内联在000_combined.sql中而非编号迁移里通过启动时的幂等 Schema 应用收敛编号迁移文件是演进史的存档000_combined.sql是它们的最终合并态文件头还注释了「布局是承重结构」的约定——所有CREATE TABLE/ADD COLUMN在前、所有引用列名的CREATE INDEX/COMMENT ON COLUMN放在末尾统一区块以规避跨语句依赖导致的中止。双后端差异速查维度SQLitePostgreSQL选择条件未设置DATABASE_URL设置了DATABASE_URL文件位置~/.archon/archon.dbWAL 模式远程连接串 / Docker 容器Schema 收敛createSchema()migrateColumns()咨询锁事务内执行合并 SQL占位符$1,$2由convertPlaceholders()转为?并重排参数原生$1,$2实时事件推送轮询器按间隔拾取pg_notify触发器实时推送尽力而为Web 登录表Better Auth不支持始终创建启用BETTER_AUTH_SECRET后写入其中 SQLite 适配器的占位符转换值得一提PostgreSQL 允许参数任意顺序引用$2 ... $1SQLite 的?只能按出现顺序绑定因此convertPlaceholders()会按出现顺序收集$N并重排参数数组同时剥掉::jsonb、::INTERVAL类型转换——这让上层可以写一套 SQL 同时跑两个后端见 sqlite.ts。SQLite 还通过事务队列txTail把withTransaction串行化避免单连接下事务嵌套抛错这与 Postgres 的Poolmax 10并发模型形成对照。实践建议小结单机/CLI 起步不设DATABASE_URL数据落在~/.archon/archon.db随时可备份该文件多容器/云端部署设置DATABASE_URLSchema 自动收敛无需手动跑迁移也不要依赖docker-entrypoint-initdb.d已冗余升级可信度发版前后跑bun run check:schema-upgrades用历史全部 Schema 基线验证幂等收敛排障入口/health/db探活日志按db.pg_schema_init_failed、db.sqlite_migration_*_failed等键定位失败阶段remote_agent_schema_version单行表可查「库由哪个版本创建、最近由哪个版本应用」删除语义会话只走软删除涉及workflow_runs/workflow_node_sessions的硬删除路径必须先行处理活跃运行与scope_key清理。以上内容全部以当前仓库的文档database.md、源码与配置为据可直接在本地复现验证。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Archon 数据库完整指南：SQLite 与 PostgreSQL 双后端架构、18 张核心表与自动化 Schema 收敛
Archon 数据库完整指南SQLite 与 PostgreSQL 双后端架构、18 张核心表与自动化 Schema 收敛【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本篇是 Archon 开源仓库的数据库参考指南覆盖从「零配置 SQLite 单机使用」到「云端 PostgreSQL 多容器部署」的完整路径。你将掌握DATABASE_URL驱动的后端自动选择机制、启动时幂等 Schema 收敛的实现原理、remote_agent_前缀下 18 张业务表的职责与关键约束以及从000_combined.sql到023的迁移演进脉络并学会用健康检查与命令行工具验证数据库状态。双后端架构一个环境变量决定一切Archon 支持两种数据库后端选择逻辑完全由环境变量DATABASE_URL驱动SQLite默认后端零配置适合单用户 CLI 使用PostgreSQL可选后端用于云端与高级部署Supabase、Neon 等托管服务或 Docker Compose 本地容器。选择逻辑位于 packages/core/src/db/connection.ts 的getDatabase()当process.env.DATABASE_URL存在时实例化PostgresAdapter否则实例化SqliteAdapter并打开~/.archon/archon.db。连接以单例形式缓存getDialect()会随后端返回对应的 SQL 方言助手如 UUID 生成、JSON 合并、日期计算上层业务代码无需关心底层是哪种数据库。从源码结构还可以看到一处贴心设计当检测到在 Docker 环境ARCHON_DOCKERtrue运行却未设置DATABASE_URL时连接层会打出db.docker_using_sqlite警告提示你可能启动了with-db的 PostgreSQL 容器但应用仍在静默使用 SQLite——这是最容易踩的坑值得部署时留意。SQLite默认零配置即用什么都不用做。只要.env中不设置DATABASE_URL应用会自动在~/.archon/archon.db创建 SQLite 数据库首次运行时自动建好父目录首次启动时初始化 Schema所有读写操作都落在这个文件上。对应实现见 packages/core/src/db/adapters/sqlite.ts 的SqliteAdapter构造器它初始化时还做了三件对并发至关重要的 PRAGMA 设置PRAGMA journal_mode WAL启用 WAL 模式提升并发读写性能PRAGMA busy_timeout 5000忙锁重试 5 秒避免并行工作流触发SQLITE_BUSYPRAGMA foreign_keys ON启用外键约束。优点零配置、无需外部数据库、单用户 CLI 场景开箱即用。缺点不适合多容器部署没有网络访问能力CLI 与 server 无法跨主机共享数据库。SQLite 的 Schema 初始化策略SQLite 没有 PostgreSQL 的CREATE TABLE IF NOT EXISTS全量幂等便利对已存在表CREATE是空操作新列不会自动补上。因此SqliteAdapter的初始化分为两步见 sqlite.ts 中initSchemacreateSchema()用带IF NOT EXISTS的 DDL 创建全部表与索引migrateColumns()用PRAGMA table_info(...)探测旧库缺失的列逐个ALTER TABLE ADD COLUMN补齐如users.role、codebases.default_branch/kind、conversations.user_id/title/deleted_at/hidden、workflow_runs.parent_run_id/adopted_from_run_id/output_root/outcome等并为新增列补建索引与触发器。值得注意的细节SQLite 端对remote_agent_workflow_events.event_order的单调递增赋值是通过AFTER INSERT触发器实现的PostgreSQL 侧则用序列且索引/触发器的创建被刻意放在migrateColumns()中而非createSchema()——因为老库在列被ALTER TABLE补上之前对缺失列建索引会直接中止整个 DDL 块。此外migrateColumns()中每个表各自的迁移失败会被单独抑制allApplied标记一次坏的ALTER不会中止启动同时避免把「未完整应用」的库错误盖上当前版本号。远程 PostgreSQLSupabase、Neon 等托管服务在.env中设置远程连接串即可DATABASE_URLpostgresql://user:passwordhost:5432/dbname无需手动执行迁移。启动时Postgres 适配器会在一个咨询锁advisory lock事务内应用打包的 migrations/000_combined.sql。该 SQL 完全幂等CREATE TABLE IF NOT EXISTS、ADD COLUMN IF NOT EXISTS、CREATE INDEX IF NOT EXISTS因此全新安装与版本升级都会自动收敛到最新 Schema——包括后续版本新增的表和列。底层机制一次启动即完成的收敛实现细节见 packages/core/src/db/adapters/postgres.ts 的initSchema()通过SELECT pg_advisory_xact_lock(1796)串行化并发启动如两个应用容器同时指向全新数据库应用前先探测to_regclass(remote_agent_codebases)判断库是否已存在用于记录创建版本在事务内执行整份幂等 SQL随后写入/更新remote_agent_schema_version单行记录诊断用途写入失败仅告警不阻断每个query()与withTransaction()都会先await schemaInitPromise保证首个数据库操作不可能与初始化竞争Schema 提交后额外安装 Postgres 专属的pg_notify触发器见下文「实时事件推送」小节该步骤失败只会降级为轮询模式不会导致启动失败。getSchemaSQL()见 packages/core/src/db/bundled-schema.ts在源码构建时直接读取磁盘上的migrations/000_combined.sql二进制构建时使用bundled-schema.generated.ts内嵌的字符串——后者由scripts/generate-bundled-schema.ts生成保证分发版本自带完整 Schema。升级是「被验证」的不是「被假设」的CI 会执行如下校验把当前 Schema 应用到一个由Archon 历史上发布过的每一个不同 Schema 版本vintage构建的数据库之上再次应用以确认幂等性然后把结果与全新安装逐项对比——包括列、索引、列注释、约束与序列。你可以在任意 PostgreSQL 上自行复跑同一检查bun run check:schema-upgrades实现位于 scripts/check-schema-upgrades.ts它会遍历 git 标签中携带的每个不同历史 Schema 快照按 blob 去重例如 v0.3.0 到 v0.3.12 字节级相同只算一份对每个基线「先应用当前 Schema、再应用一遍、再与全新库 diff」任何一项不一致都会输出FAIL并给出退出码。失败处理若 Schema 应用失败权限不足、语法错误、网络问题进程会在首个数据库操作处中止底层 Postgres 错误以db.pg_schema_init_failed为键记录日志。本地 PostgreSQLDocker Composewith-dbProfile使用仓库根目录 docker-compose.yml 的with-dbprofile 可一键拉起本地 PostgreSQLdocker compose --profile with-db up -d然后在.env中设置连接串DATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agent其中postgres是 Compose 内的服务名remote_coding_agent是镜像初始化时创建的数据库名POSTGRES_DB。Compose 中 PostgreSQL 服务还暴露了127.0.0.1:5432端口方便本机psql直连。与远程 PostgreSQL 完全相同应用启动时自动收敛 Schema——全新安装与升级走同一条路径。原先docker compose up -d中docker-entrypoint-initdb.d挂载的migrations/000_combined.sql现在已冗余仅作为全新卷上的空操作no-op保留。注意Docker 部署下若忘了设置DATABASE_URL应用会退回 SQLite 并在日志中输出db.docker_using_sqlite警告数据库不会自动「切」到 Postgres 容器。验证数据库状态健康检查端点实现于 packages/server/src/index.ts 的/health/db路由内部执行SELECT 1curl http://localhost:3090/health/db # Expected: {status:ok,database:connected}失败时返回 HTTP 500 与{status:error,database:disconnected}。列出全部表PostgreSQLpsql $DATABASE_URL -c \dtSQLite可直接查看 Schema 版本记录sqlite3 ~/.archon/archon.db SELECT * FROM remote_agent_schema_version;remote_agent_schema_version是单行诊断表id 1记录「由哪个 Archon 构建创建」「最近一次由哪个构建应用 Schema」对排查「数据库是从哪个版本升上来的」非常有用。Schema 全景18 张remote_agent_表所有业务表统一以remote_agent_为前缀共 18 张。完整 DDL 见 migrations/000_combined.sqlSQLite 版本见 packages/core/src/db/adapters/sqlite.ts 的createSchema()。下面按职责分组逐表说明。仓库与项目1.remote_agent_codebases— 仓库元数据命令以 JSONB 存储{command_name: {path, description}}每个 codebase 的 AI 助手类型ai_assistant_type默认claude默认工作目录default_cwdkindrepo|folder默认repo区分 git 仓库项目与非 git 文件夹项目后者原地运行不走 worktree可空的已探测默认分支default_branch存在时作为工作区同步的分支上下文。8.remote_agent_codebase_env_vars— 项目级环境变量键值对作用域限定到单个 codebaseUNIQUE(codebase_id, key)执行时注入 Claude SDK 子进程环境源码注释merged into Options.env on Claude SDK callsWeb UI 的 Settings 面板管理CLI 用户通过.archon/config.yaml中的env:配置另有remote_agent_codebases.allow_env_keys布尔列控制是否放行。对话与消息2.remote_agent_conversations— 平台会话跟踪platform_typeplatform_conversation_id唯一约束同一平台会话只对应一行通过外键关联 codebaseAI 助手类型在创建时锁定可空user_id记录创建会话的首个用户first-user-wins同线程后续回复归属在workflow_run上而非这里deleted_at/hidden支撑软删除与隐藏。7.remote_agent_messages— 会话消息历史持久化用户与助手消息及时间戳支撑 Web UI 刷新后仍能恢复历史工具调用元数据名称、输入、耗时存于 JSONB可空user_id只出现在role user的行上助手行的该列为 NULL。3.remote_agent_sessions— AI 会话管理活跃会话标志每会话一个assistant_session_id提供恢复resume能力metadataJSONB 存命令上下文parent_session_id自引用 FK 构成会话谱系transition_reason/ended_reason记录会话流转与结束原因对应迁移 010、016。工作流执行与可观测性4.remote_agent_isolation_environments— Worktree 隔离按 issue/PR 跟踪 git worktree支持关联 issue 与 PR 间共享 worktreeworkflow_typeissue/pr/review/thread/taskworkflow_id标识工作可空created_by_user_id跨重新激活保留原始创建者ON CONFLICT DO UPDATE刻意不更新该列活跃状态唯一性由部分唯一索引unique_active_workflow仅status active保证。5.remote_agent_workflow_runs— 工作流执行追踪记录每个会话的活跃工作流status取pending/running/completed/failed/cancelled/paused同路径并发锁对同一working_path若已有pending/running/paused的活跃运行第二次派发会被自动取消并给出可操作提示超过 5 分钟的陈旧pending行视为孤儿忽略workflow:子运行共享父运行 checkout除非节点声明isolation: worktree因此路径锁排除祖先链与后代经parent_run_id子运行不会与自己的父运行竞争但兄弟运行之间不排除可空parent_run_id自引用 FKON DELETE SET NULL把workflow:子运行链接到产生它的父运行顶层运行为 NULL。使运行树可遍历findChildRuns/getRunAncestry支撑 abandon 级联与成本汇总adopted_from_run_id记录跨运行延续写一次恢复时不改写output_root是运行开始时解析的~/.archon/workspaces/project/目录使历史产物在 codebase 改名后依然可寻conversation_id在会话删除时级联对会话的硬DELETE会连带抹掉运行行并静默丢失其隔离环境的 live-run 清理 pin——因此软删除是唯一受支持的路径未来若实现硬删除必须先解决活跃运行的清理。6.remote_agent_workflow_events— 步骤级事件日志记录每次运行的步骤转换、产物与错误只存精简的 UI 相关事件详细日志在 JSONL 文件中支撑运行详情视图与调试在created_at上建索引idx_workflow_events_created_at供仪表盘事件轮询器做跨运行尾部读取。11.remote_agent_workflow_node_sessions— 跨重跑的节点级 provider 会话通过persist_session可选启用以(workflow_name, node_id, scope_key, provider)为主键scope_key通常是会话 UUID不设外键因此会话删除不会级联到这里——软删除 永不复用的 UUID 让残留无害未来硬删除需按scope_key自行清理与workflow_runs级联警示互为镜像。另有源码中可见的两张辅助表remote_agent_schema_version前述诊断用与remote_agent_workflow_run_node_sessions单次运行内部、按(workflow_run_id, node_id)主键、随运行级联、不通过 API 暴露的私有会话句柄。用户与身份9.remote_agent_users— Archon 内部用户身份每个人类或机器人跨平台一行任何 chat/forge 适配器首次见到即惰性创建display_name与email在充实成功前可空roleVARCHAR默认admin是为未来按资源做权限划分预留的身份接缝——当前所有人都是admin可见性保持开放member为保留值。10.remote_agent_user_identities— 平台到 Archon 用户的映射每个(platform, platform_user_id)一行——Slack U-id、Telegram chat id、Discord snowflake、GitHub login、Web 端 Better Auth 用户 id 等UNIQUE(platform, platform_user_id)在数据库层去重引用users.id时ON DELETE CASCADE删用户即删其身份映射与之相对四个业务表上的所有user_id外键都用ON DELETE SET NULL确保未来删除用户不会造成破坏性级联。12.remote_agent_user_github_tokens— 每用户 GitHub device-flow 令牌静态加密AES-256-GCM每 Archon 用户一行UNIQUE(user_id)随用户删除级联数值型github_user_id锚定 commit 的 no-reply 邮箱。13.remote_agent_user_provider_keys— 每用户 AI provider 凭据API Key 或 OAuth 订阅 blob静态加密AES-256-GCM使用同一个TOKEN_ENCRYPTION_KEY每(user_id, provider)一行随用户删除级联kind区分api_key与oauth执行时解析并注入用户运行/聊天的环境provider保存厂商规范凭据 idanthropic、openai、github-copilot以及 Pi 后端厂商——历史遗留的claude/codex/copilot行由启动时的幂等数据修复改名两者并存时厂商行胜出。14.remote_agent_user_ai_prefs— 每用户 AI 偏好个人模型层级、custom别名、默认助手与默认聊天模型不加密模型名不是秘密每用户一行UNIQUE(user_id)随用户删除级联tiers/aliases为 JSON-as-TEXT作为最高优先级层参与模型解析default_model钉住用户的直接聊天模型与default_provider原子写入仅当生效聊天 provider 匹配时应用工作流仍解析large层级解析遵循行为用户工作流运行用运行发起者聊天轮次用消息发送者会话创建者的行仅在无法解析发送者身份时作为兜底编辑入口控制台 Just me 作用域、archon ai … --scope user、/api/auth/me/ai-prefs*。15–18.remote_agent_auth_user/remote_agent_auth_session/remote_agent_auth_account/remote_agent_auth_verification— Better Auth 表可选 Web 登录仅 PostgreSQL。Postgres 上由幂等 Schema 应用总是创建但仅在启用 Web 认证DATABASE_URLBETTER_AUTH_SECRET时才写入数据归 Better Auth 所有并塑形文本 id、camelCase 列Archon 从不直接查询它们——一个 session 经由user_identities(web, betterAuthUserId)映射到规范的users行。PostgreSQL 专属实时事件推送在 PostgreSQL 上remote_agent_workflow_events存在一个AFTER INSERT触发器archon_workflow_event_notify调用pg_notify(archon_dashboard_event, …)使得进程外启动的运行archonCLI /--detach也能实时流式进入控制台SQLite 上则由轮询器按间隔拾取。该触发器仅限 Postgres 且尽力而为——角色无CREATE TRIGGER权限时降级为纯轮询不会导致启动失败对应 postgres.ts 中installNotifyTrigger()的独立事务与告警日志db.postgres_notify_trigger_install_failed。迁移清单与版本演进migrations/目录下的迁移文件按时间线演进SQLite 端则由createSchema()migrateColumns()内联完成等效变更迁移说明000_combined.sql合并后的初始 Schema全新安装用这份001_initial_schema.sql初始 Schemacodebases、conversations、sessions002_command_templates.sql命令模板表003_add_worktree.sql添加 worktree 列004_worktree_sharing.sqlworktree 共享支持005_isolation_abstraction.sql隔离抽象层006_isolation_environments.sql隔离环境表007_drop_legacy_columns.sql删除遗留 worktree 列008_workflow_runs.sql工作流运行表009_workflow_last_activity.sql工作流最近活动追踪010_immutable_sessions.sql不可变会话模型011_partial_unique_constraint.sql部分唯一约束012_workflow_events.sql工作流事件表013_conversation_titles.sql会话标题014_message_history.sql消息历史表015_background_dispatch.sql后台派发支持016_session_ended_reason.sql会话结束原因字段017_drop_command_templates.sql删除命令模板表018_fix_workflow_status_default.sql修复工作流状态默认值019_workflow_resume_path.sql工作流恢复路径支持020_codebase_env_vars.sql项目级环境变量021_add_allow_env_keys_to_codebases.sql每 codebase 的放行 env 键022_workflow_node_sessions.sql每节点 provider 会话持久化023_add_default_branch_to_codebases.sqlcodebases 上探测的默认分支几点说明均以当前仓库实际内容为准早期通过002引入、017移除的remote_agent_command_templates已被文件化命令.archon/commands取代——000_combined.sql 开头也以DROP TABLE IF EXISTS清理遗留对象remote_agent_codebases.kind列、remote_agent_users.role列以及四张remote_agent_auth_*Better Auth 表是内联在000_combined.sql中而非编号迁移里通过启动时的幂等 Schema 应用收敛编号迁移文件是演进史的存档000_combined.sql是它们的最终合并态文件头还注释了「布局是承重结构」的约定——所有CREATE TABLE/ADD COLUMN在前、所有引用列名的CREATE INDEX/COMMENT ON COLUMN放在末尾统一区块以规避跨语句依赖导致的中止。双后端差异速查维度SQLitePostgreSQL选择条件未设置DATABASE_URL设置了DATABASE_URL文件位置~/.archon/archon.dbWAL 模式远程连接串 / Docker 容器Schema 收敛createSchema()migrateColumns()咨询锁事务内执行合并 SQL占位符$1,$2由convertPlaceholders()转为?并重排参数原生$1,$2实时事件推送轮询器按间隔拾取pg_notify触发器实时推送尽力而为Web 登录表Better Auth不支持始终创建启用BETTER_AUTH_SECRET后写入其中 SQLite 适配器的占位符转换值得一提PostgreSQL 允许参数任意顺序引用$2 ... $1SQLite 的?只能按出现顺序绑定因此convertPlaceholders()会按出现顺序收集$N并重排参数数组同时剥掉::jsonb、::INTERVAL类型转换——这让上层可以写一套 SQL 同时跑两个后端见 sqlite.ts。SQLite 还通过事务队列txTail把withTransaction串行化避免单连接下事务嵌套抛错这与 Postgres 的Poolmax 10并发模型形成对照。实践建议小结单机/CLI 起步不设DATABASE_URL数据落在~/.archon/archon.db随时可备份该文件多容器/云端部署设置DATABASE_URLSchema 自动收敛无需手动跑迁移也不要依赖docker-entrypoint-initdb.d已冗余升级可信度发版前后跑bun run check:schema-upgrades用历史全部 Schema 基线验证幂等收敛排障入口/health/db探活日志按db.pg_schema_init_failed、db.sqlite_migration_*_failed等键定位失败阶段remote_agent_schema_version单行表可查「库由哪个版本创建、最近由哪个版本应用」删除语义会话只走软删除涉及workflow_runs/workflow_node_sessions的硬删除路径必须先行处理活跃运行与scope_key清理。以上内容全部以当前仓库的文档database.md、源码与配置为据可直接在本地复现验证。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考