BCAI/easyai-ai-gateway
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

chore(dev): 配置本地开发环境 #1

Merged
chensipeng merged 2 commits from chore/devenv-setup into main 2026-05-15 09:46:38 +08:00
Conversation 0 Commits 2 Files Changed 6 +303 -1
chensipeng commented 2026-05-13 15:11:48 +08:00
Owner
Copy Link

背景

本 PR 为 EasyAI AI Gateway 增加基于 devenv/Nix 的本地开发环境配置，目标是让新成员或新机器可以用统一入口获得一致的 Go、Node.js、pnpm、PostgreSQL 与常用调试工具，减少手工安装、版本漂移和数据库初始化差异。

变更内容

  • 新增 devenv.nix，声明项目本地开发环境：

    • 启用 Go 与 JavaScript/Node.js 开发语言环境。
    • 固定 Node.js 22、当前 nixpkgs 中的 Go、pnpm、PostgreSQL 18 等工具来源。
    • 自动启用 pnpm install，进入环境后按项目根 package.json 安装依赖。
    • 提供 dev、build、test-all、lint、migrate、db-create、api-test、web-build 等短命令，统一转发到根 package scripts 或 Nx 目标。
    • 启动 devenv 管理的 PostgreSQL 服务，并预创建 easyai_ai_gateway 数据库。
    • 初始化 pgcrypto 与 vector 扩展，匹配 API 侧加密、向量能力相关依赖。
    • 设置 AI_GATEWAY_DATABASE_URL 指向 devenv runtime 下的 PostgreSQL Unix socket，避免和本机 Docker/PostgreSQL TCP 端口互相影响。
    • 设置 AI_GATEWAY_SKIP_DB_CREATE=1，避免在 devenv 环境内重复调用 Docker 数据库创建逻辑。

  • 新增 devenv.yaml 与 devenv.lock：

    • devenv.yaml 声明 devenv 使用的 nixpkgs 输入来源。
    • devenv.lock 锁定 devenv 与 nixpkgs 实际 revision，保证不同机器进入环境时拿到一致依赖图。

  • 新增 starship.toml：

    • 为 devenv shell 启用紧凑提示符。
    • 展示目录、Git 分支/状态、Nix shell 状态、Node/Go 版本、命令耗时、内存与上一条命令状态。
    • 使用纯文本符号，降低跨终端、日志和 AI 工具解析时的乱码风险。

  • 调整 scripts/dev.sh：

    • 保留原有 Docker/PostgreSQL 默认开发路径。
    • 当 AI_GATEWAY_SKIP_DB_CREATE=1 时跳过 Docker 数据库创建，适配 devenv 管理 PostgreSQL 的场景。
    • 仍会执行 API 迁移，并启动 API/Web dev target。

  • 更新 .gitignore：

    • 忽略 .devenv*、devenv.local.nix、devenv.local.yaml 和 .direnv 等本地环境产物。
    • 避免本地 devenv state、direnv 缓存和个人覆盖配置进入版本库。

devenv 的作用

devenv 是项目级开发环境编排工具。它把“进入项目后需要哪些工具、哪些服务、哪些环境变量、哪些快捷命令”写进仓库配置中。对本项目来说，devenv 主要承担：

  • 自动准备 Go、Node.js、pnpm、PostgreSQL、jq、ripgrep、watchexec 等开发依赖。
  • 进入 shell 时输出当前运行时版本和常用命令，降低新成员上手成本。
  • 统一本地数据库名称、连接方式和扩展初始化。
  • 把项目常用命令集中成短命令，避免每人记不同的 Nx/package script 组合。
  • 让开发环境可审查、可复现、可随代码一起演进。

Nix 的作用

Nix 是 devenv 底层使用的可复现包管理与构建系统。它的价值不只是“安装工具”，而是让工具来源、版本和依赖闭包可声明、可锁定、可复现。对本项目来说，Nix 主要提供：

  • 按 devenv.lock 锁定依赖输入，减少不同机器上的版本漂移。
  • 通过隔离 store 提供 Go、Node.js、PostgreSQL 等工具，不依赖宿主机全局安装版本。
  • 支持在 macOS/Linux 上尽量使用同一套环境描述。
  • 让开发环境变更像代码一样进入 review 流程，避免隐式环境假设。

使用方式

  • 安装 Nix 与 devenv 后，在仓库根目录运行 devenv shell 进入开发环境。
  • 进入环境后可直接运行：
    • dev：创建/迁移数据库，并启动 API 与 Web。
    • test-all：运行 API 与 Web 测试目标。
    • build：构建 API 与 Web。
    • lint：运行 Web 与 contracts 类型检查。
    • migrate：执行 API 数据库迁移。
    • api-test：只运行 Go API 测试。
    • web-build：只构建 Web 前端。

验证

  • devenv test --no-tui --override-dotfile
  • devenv shell --no-tui -- pnpm lint
  • devenv shell --no-tui -- pnpm test
  • devenv shell --no-tui -- pnpm build

说明：直接运行 devenv test --no-tui 时，本机已有同一 devenv PostgreSQL socket lock，占用 /tmp/devenv-d4e760e/postgres/.s.PGSQL.5432.lock，导致 postgres 进程启动冲突；使用 --override-dotfile 隔离 state 后验证通过。

风险与影响

  • 运行时业务代码无变更，主要影响本地开发环境和启动路径。
  • scripts/dev.sh 新增的 AI_GATEWAY_SKIP_DB_CREATE 分支只在显式设置该环境变量时生效，不影响默认 Docker 数据库创建流程。
  • devenv.lock 会固定当前 devenv/nixpkgs 输入，后续升级工具链需要通过更新 lock 文件进入 review。
## 背景 本 PR 为 EasyAI AI Gateway 增加基于 devenv/Nix 的本地开发环境配置，目标是让新成员或新机器可以用统一入口获得一致的 Go、Node.js、pnpm、PostgreSQL 与常用调试工具，减少手工安装、版本漂移和数据库初始化差异。 ## 变更内容 - 新增 `devenv.nix`，声明项目本地开发环境： - 启用 Go 与 JavaScript/Node.js 开发语言环境。 - 固定 Node.js 22、当前 nixpkgs 中的 Go、pnpm、PostgreSQL 18 等工具来源。 - 自动启用 pnpm install，进入环境后按项目根 `package.json` 安装依赖。 - 提供 `dev`、`build`、`test-all`、`lint`、`migrate`、`db-create`、`api-test`、`web-build` 等短命令，统一转发到根 package scripts 或 Nx 目标。 - 启动 devenv 管理的 PostgreSQL 服务，并预创建 `easyai_ai_gateway` 数据库。 - 初始化 `pgcrypto` 与 `vector` 扩展，匹配 API 侧加密、向量能力相关依赖。 - 设置 `AI_GATEWAY_DATABASE_URL` 指向 devenv runtime 下的 PostgreSQL Unix socket，避免和本机 Docker/PostgreSQL TCP 端口互相影响。 - 设置 `AI_GATEWAY_SKIP_DB_CREATE=1`，避免在 devenv 环境内重复调用 Docker 数据库创建逻辑。 - 新增 `devenv.yaml` 与 `devenv.lock`： - `devenv.yaml` 声明 devenv 使用的 nixpkgs 输入来源。 - `devenv.lock` 锁定 devenv 与 nixpkgs 实际 revision，保证不同机器进入环境时拿到一致依赖图。 - 新增 `starship.toml`： - 为 devenv shell 启用紧凑提示符。 - 展示目录、Git 分支/状态、Nix shell 状态、Node/Go 版本、命令耗时、内存与上一条命令状态。 - 使用纯文本符号，降低跨终端、日志和 AI 工具解析时的乱码风险。 - 调整 `scripts/dev.sh`： - 保留原有 Docker/PostgreSQL 默认开发路径。 - 当 `AI_GATEWAY_SKIP_DB_CREATE=1` 时跳过 Docker 数据库创建，适配 devenv 管理 PostgreSQL 的场景。 - 仍会执行 API 迁移，并启动 API/Web dev target。 - 更新 `.gitignore`： - 忽略 `.devenv*`、`devenv.local.nix`、`devenv.local.yaml` 和 `.direnv` 等本地环境产物。 - 避免本地 devenv state、direnv 缓存和个人覆盖配置进入版本库。 ## devenv 的作用 `devenv` 是项目级开发环境编排工具。它把“进入项目后需要哪些工具、哪些服务、哪些环境变量、哪些快捷命令”写进仓库配置中。对本项目来说，devenv 主要承担： - 自动准备 Go、Node.js、pnpm、PostgreSQL、jq、ripgrep、watchexec 等开发依赖。 - 进入 shell 时输出当前运行时版本和常用命令，降低新成员上手成本。 - 统一本地数据库名称、连接方式和扩展初始化。 - 把项目常用命令集中成短命令，避免每人记不同的 Nx/package script 组合。 - 让开发环境可审查、可复现、可随代码一起演进。 ## Nix 的作用 `Nix` 是 devenv 底层使用的可复现包管理与构建系统。它的价值不只是“安装工具”，而是让工具来源、版本和依赖闭包可声明、可锁定、可复现。对本项目来说，Nix 主要提供： - 按 `devenv.lock` 锁定依赖输入，减少不同机器上的版本漂移。 - 通过隔离 store 提供 Go、Node.js、PostgreSQL 等工具，不依赖宿主机全局安装版本。 - 支持在 macOS/Linux 上尽量使用同一套环境描述。 - 让开发环境变更像代码一样进入 review 流程，避免隐式环境假设。 ## 使用方式 - 安装 Nix 与 devenv 后，在仓库根目录运行 `devenv shell` 进入开发环境。 - 进入环境后可直接运行： - `dev`：创建/迁移数据库，并启动 API 与 Web。 - `test-all`：运行 API 与 Web 测试目标。 - `build`：构建 API 与 Web。 - `lint`：运行 Web 与 contracts 类型检查。 - `migrate`：执行 API 数据库迁移。 - `api-test`：只运行 Go API 测试。 - `web-build`：只构建 Web 前端。 ## 验证 - `devenv test --no-tui --override-dotfile` - `devenv shell --no-tui -- pnpm lint` - `devenv shell --no-tui -- pnpm test` - `devenv shell --no-tui -- pnpm build` 说明：直接运行 `devenv test --no-tui` 时，本机已有同一 devenv PostgreSQL socket lock，占用 `/tmp/devenv-d4e760e/postgres/.s.PGSQL.5432.lock`，导致 postgres 进程启动冲突；使用 `--override-dotfile` 隔离 state 后验证通过。 ## 风险与影响 - 运行时业务代码无变更，主要影响本地开发环境和启动路径。 - `scripts/dev.sh` 新增的 `AI_GATEWAY_SKIP_DB_CREATE` 分支只在显式设置该环境变量时生效，不影响默认 Docker 数据库创建流程。 - `devenv.lock` 会固定当前 devenv/nixpkgs 输入，后续升级工具链需要通过更新 lock 文件进入 review。
chensipeng added 1 commit 2026-05-13 15:11:51 +08:00 
引入 devenv 与 starship 配置，统一 Go/Node/Postgres 开发依赖与快捷命令。
同时让脚本在使用本地数据库环境时跳过 Docker 创建步骤。
chensipeng requested review from wangbo 2026-05-13 15:16:29 +08:00
chensipeng added 1 commit 2026-05-15 09:45:33 +08:00
chensipeng merged commit 62d426bdfb into main 2026-05-15 09:46:38 +08:00
Sign in to join this conversation.
Reviewers
No reviewers
wangbo
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: BCAI/easyai-ai-gateway#1
No description provided.
Delete Branch "chore/devenv-setup"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?