环境搭建与本地开发启动指南

本指南面向初次接触 Cybros 单仓库的开发者，系统性地讲解如何从零搭建本地开发环境、理解启动流程、配置关键参数，并成功运行完整的开发服务器。Cybros 由 Core Matrix 内核平台和 Fenix 代理程序两个 Rails 应用组成，它们共享一套基于 foreman 的进程管理架构，但拥有各自独立的依赖栈和数据库。阅读完本文后，你将拥有一个可以正常工作的本地开发实例，并理解每个配置项的作用。

Sources: README.md, AGENTS.md

先决条件与版本要求

Cybros 的两个子项目各有独立的运行时依赖。在开始之前，请确认本地已安装以下工具链：

关键说明：Core Matrix 的生产 Docker 镜像使用 pgvector/pgvector:pg18-trixie 镜像，其中包含 PostgreSQL 18 和 pgvector 扩展。本地开发环境如果使用原生 PostgreSQL，需确保安装了 pgvector 扩展。开发环境中 Bun 仅用于 Core Matrix 的前端资源打包（通过 bun.config.js 监听 app/javascript 目录并输出到 app/assets/builds），Fenix 不使用 Bun 而是使用 npm 管理其 Playwright 依赖。

Sources: core_matrix/.ruby-version, agents/fenix/.ruby-version, core_matrix/Dockerfile, core_matrix/compose.yaml.sample, agents/fenix/.node-version, agents/fenix/.python-version, core_matrix/Gemfile

架构总览：开发环境中的进程拓扑

在深入配置步骤之前，理解 Cybros 开发环境运行时会启动哪些进程至关重要。下图展示了从仓库根目录启动 bin/dev 时的完整进程拓扑：

核心设计要点：bin/dev（根目录入口）是一个 Ruby 脚本，它首先通过 MonorepoDevEnvironment 模块注入默认环境变量（端口号、服务 URL），然后同时启动 Rails server 和 foreman 进程管理器。Foreman 读取根目录的 Procfile.dev，按需启动后台作业工作器、前端构建监视器和 Fenix 子进程。Rails server 和 foreman 是两个独立的顶层进程，当 Rails server 退出时，bin/dev 会发送 INT 信号给 foreman 进程组，确保所有子进程干净退出。

Sources: bin/dev, lib/monorepo_dev_environment.rb, Procfile.dev, core_matrix/Procfile.dev

步骤一：Core Matrix 环境配置

Core Matrix 是整个平台的核心，它依赖 PostgreSQL 多数据库架构和 Solid Queue 后台任务系统。以下是从零开始的配置流程：

1.1 克隆仓库并安装基础工具

git clone <repository-url> cybros.new
cd cybros.new

确保已通过版本管理器（如 rbenv、rvm 或 mise）安装 Ruby 4.0.2。项目根目录和两个子项目都有各自的 .ruby-version 文件，内容均为 4.0.2。

Sources: core_matrix/.ruby-version, agents/fenix/.ruby-version

1.2 PostgreSQL 数据库准备

Core Matrix 在开发环境中使用 三个独立数据库，全部由同一个 PostgreSQL 实例承载：

如果 PostgreSQL 运行在默认的 Unix socket 或 localhost:5432 上，不需要任何额外配置，bin/rails db:prepare 会自动创建这些数据库并运行迁移。如果 PostgreSQL 运行在其他位置，请在 .env 中设置 RAILS_DB_URL_BASE，例如：

# .env 文件
RAILS_DB_URL_BASE=postgresql://postgres:postgres@localhost:5432

Sources: core_matrix/config/database.yml, core_matrix/env.sample

1.3 安装依赖

在 core_matrix 目录下执行：

cd core_matrix
bundle install          # 安装 Ruby 依赖（包含 Rails main 分支）
bun install             # 安装前端依赖（Tailwind CSS 4, Stimulus, Turbo 等）

注意事项：Core Matrix 的 Gemfile 使用了 Rails 主分支（gem "rails", github: "rails/rails", branch: "main"），首次 bundle install 可能需要较长时间。此外，vendor/simple_inference 是一个内嵌的本地 gem，通过 path 方式引用。

Sources: core_matrix/Gemfile, core_matrix/bin/setup

1.4 环境变量配置

Core Matrix 的环境变量模板位于 env.sample，复制并按需填写：

cp env.sample .env

对于纯本地开发，绝大多数变量可以保持默认。以下是按优先级排列的配置清单：

如果你需要连接真实的 LLM API 进行端到端测试，还需要配置以下变量（它们会在 db:seed 时被读取并持久化为 ProviderCredential）：

Sources: core_matrix/env.sample, core_matrix/db/seeds.rb

1.5 数据库初始化

bin/rails db:prepare

此命令会自动创建三个数据库、运行所有迁移、并加载种子数据。种子数据（db/seeds.rb）会执行以下操作：注册内嵌代理运行时、为 dev provider 创建默认策略和配额、以及（如果提供了 API 密钥）为 OpenAI/OpenRouter 创建凭据和策略。

如果需要完全重置数据库：

bin/rails db:reset

Sources: core_matrix/bin/setup, core_matrix/db/seeds.rb

步骤二：Fenix 代理程序环境配置

Fenix 是 Cybros 的默认代理程序，它使用 SQLite 作为数据库（无需 PostgreSQL），但需要 Node.js 和 Python 来支持浏览器自动化功能。Fenix 的配置流程相对简化：

cd agents/fenix
bundle install          # Ruby 依赖（Rails main + SQLite + WebSocket）
npm install             # Node.js 依赖（Playwright 浏览器自动化）

Fenix 同样提供了 env.sample 文件，但对于本地开发，最关键的是与 Core Matrix 的配对配置：

独立运行说明：Fenix 的 Docker 生产配置暴露端口 3101，但通过单仓库 Procfile.dev 启动时，Fenix 使用端口 36173（由 MonorepoDevEnvironment::AGENT_FENIX_PORT 定义）。如果只单独启动 Core Matrix，Fenix 相关的配置可以暂时跳过。

Sources: agents/fenix/env.sample, agents/fenix/Gemfile, agents/fenix/package.json, lib/monorepo_dev_environment.rb

步骤三：启动开发服务器

Cybros 提供了两种启动方式：单仓库模式（同时启动所有服务）和单项目模式（只启动 Core Matrix）。

3.1 单仓库模式（推荐）

从仓库根目录执行：

bin/dev

这个命令的工作原理如下：首先，它加载 MonorepoDevEnvironment.defaults 注入环境变量（PORT=3000、AGENT_FENIX_PORT=36173、AGENT_FENIX_BASE_URL 等）。然后，它同时启动两个并行进程——一个直接运行 core_matrix/bin/rails server，另一个通过 foreman 读取根目录 Procfile.dev 启动以下辅助服务：

当 Rails server 进程退出时（例如按 Ctrl+C），脚本会向 foreman 进程组发送 INT 信号，确保所有子进程干净终止。添加 --verbose 或 -v 参数可以查看 foreman 的详细输出。

Sources: bin/dev, lib/monorepo_dev_environment.rb, Procfile.dev

3.2 仅启动 Core Matrix

如果不需要 Fenix，可以在 core_matrix 目录下单独启动：

cd core_matrix
bin/setup            # 一键式：安装依赖 → 准备数据库 → 启动服务器

或者更细粒度地控制：

cd core_matrix
bin/setup --skip-server    # 只安装依赖和准备数据库，不启动服务器
bin/dev                    # 手动启动开发服务器

Core Matrix 的 bin/dev 同样使用 foreman + Procfile.dev 模式，但其 Procfile 包含了 web 进程（Puma server），而单仓库根的 Procfile 没有 web——因为根入口自己直接启动了 Rails server。

Core Matrix Procfile.dev 与根 Procfile.dev 对比：

Sources: core_matrix/bin/dev, core_matrix/bin/setup, core_matrix/Procfile.dev

3.3 使用一键安装脚本

Core Matrix 提供了 bin/setup 脚本，它是幂等的（可以安全地重复运行）：

cd core_matrix
bin/setup                # 安装依赖 → 准备数据库 → 启动 dev server
bin/setup --reset        # 同上，但先重置数据库
bin/setup --skip-server  # 只准备环境，不启动服务器

Sources: core_matrix/bin/setup

步骤四：Dev Container 方式（可选）

对于偏好容器化开发环境的开发者，Core Matrix 提供了完整的 VS Code Dev Container 配置。该配置位于 core_matrix/.devcontainer/ 目录，包含：

Dev Container 的 postCreateCommand 会自动执行 bin/setup --skip-server，完成依赖安装和数据库准备。容器内通过 forwardPorts 暴露 3000（Rails）和 5432（PostgreSQL）端口。

Sources: core_matrix/.devcontainer/devcontainer.json, core_matrix/.devcontainer/compose.yaml, core_matrix/.devcontainer/Dockerfile

配置详解：Solid Queue 与运行时拓扑

Core Matrix 使用 Solid Queue 作为后台任务适配器，并通过 config/runtime_topology.yml 定义了精细化的队列拓扑。开发环境默认拓扑如下：

每个队列的线程数和进程数都可通过环境变量覆盖（例如 SQ_THREADS_LLM_OPENAI=5），这使得同一份 config/queue.yml 可以适配不同规模的部署。config/runtime_topology.yml 是队列拓扑的唯一数据源，config/queue.yml 通过 ERB 模板从中读取配置。

连接池计算：数据库连接池大小（RAILS_DB_POOL）必须满足：>= 所有 Solid Queue 工作线程总数 + 2。默认拓扑下总线程数约为 19，因此默认连接池为 16 可能偏紧——如果看到连接池耗尽的错误，建议显式设置 RAILS_DB_POOL=24。

Sources: core_matrix/config/runtime_topology.yml, core_matrix/config/queue.yml, core_matrix/env.sample, core_matrix/config/environments/development.rb

LLM Provider 目录配置

Core Matrix 通过 config/llm_catalog.yml 定义了所有可用的 LLM Provider 和模型。该目录在开发环境中默认包含以下 provider：

你可以通过在 config.d/ 目录下放置 llm_catalog.yml 或 llm_catalog.development.yml 文件来覆盖基础目录。该机制支持 深度合并（Hash 值逐层合并）和 数组替换（数组直接覆盖），非常适合在不修改源文件的情况下添加自定义模型或调整参数。

Sources: core_matrix/config/llm_catalog.yml, core_matrix/config.d/llm_catalog.yml.sample

常见问题排查

Sources: core_matrix/config/database.yml, core_matrix/config/puma.rb, core_matrix/config/environments/development.rb

验证命令速查

成功启动后，可以通过以下命令验证环境完整性。这些命令与 CI 流水线使用的验证步骤一致：

# Core Matrix 验证（在 core_matrix 目录下执行）
cd core_matrix
bin/rails db:test:prepare test       # 单元/集成测试
bin/rails db:test:prepare test:system # 系统测试
bin/brakeman --no-pager               # 安全扫描
bin/bundler-audit                     # 依赖漏洞检查
bin/rubocop -f github                 # 代码风格检查
bun run lint:js                       # JavaScript 代码风格检查

# Fenix 验证（在 agents/fenix 目录下执行）
cd agents/fenix
bin/rails db:test:prepare test        # 单元测试
bin/brakeman --no-pager               # 安全扫描
bin/bundler-audit                     # 依赖漏洞检查
bin/rubocop -f github                 # 代码风格检查

Sources: AGENTS.md

下一步

环境搭建完成后，建议按以下顺序深入学习：

1. Docker Compose 部署参考 — 了解如何通过容器化方式部署完整的生产级 Cybros 堆栈
2. 六大限界上下文与领域模型总览 — 理解 Core Matrix 的核心领域架构和数据库表结构
3. LLM Provider 目录与模型选择解析 — 深入了解 Provider 目录的配置机制和模型角色选择策略
4. 运行时拓扑与 Solid Queue 队列配置 — 掌握队列调优和生产环境拓扑规划