@adamhancock/devctl2

中文文档

1.1.4发布于 2026/08/31MITTypeScriptES Module构建来源已验证近 30 天下载 2319

具有可配置应用程序、凯迪、数据库隔离和港口管理的多工作树项目通用开发环境管理员

文档目录36 节

特征
安装
地方发展
从npm起(已公布)
快速启动
配置
示例配置
配置选项
图标
devctl setup [name]
devctl list 编号 : devctl ls
devctl remove <subdomain> 编号 : devctl rm <subdomain>
devctl ports <subdomain>
devctl init [project-name]
数据库命令
devctl doctor
工作流程示例
设立新功能分支
与数据库合作
清理
所需资源
凯迪设置
PostgreSQL 设置
如何运作
港口配置
数据库隔离
凯迪跑道
解决问题
凯迪没有运行
未找到 PostgreSQL 工具
港口冲突
数据库连接出错
路线不工作
发展
许可证
捐款

脱钩

大力发展多工作树项目环境管理人员. 通过自动处理来简化开发环境的管理:

凯迪反向代理路由 基于子域的工作树
数据库隔离 每个工作树自动创建 PostgreSQL 数据库
端口分配 避免冲突
环境文件管理 有自动 .env 更新
MCP一体化 claude 代码和焦点

特征

拥有子域或根域支持的自动凯迪路由设置
从模板创建 PostgreSQL 数据库
根据工作树路径来决定端口分配
在所有软件包中自动更新.env文件
QQ 数据库备份并恢复功能
QQ 调试的焦点集成
QQ MCP( 模式上下文协议) 配置
* 内设健康检查和诊断

安装

地方发展

# Install dependencies
pnpm install

# Build the package
pnpm build

# Link globally for local testing
npm link

从npm起(已公布)

npm install -g devctl
# or
pnpm add -g devctl

快速启动

在您的工程中初始化配置 :

cd /path/to/your/project
devctl init my-project

编辑 .devctlrc.json 以匹配您的工程结构
设置工作树 :

cd /path/to/your/worktree
devctl setup

配置

创建一个 .devctlrc.json 中的文件。你用得着 devctl init [project-name] 生成启动配置.

示例配置

{
  "projectName": "my-project",
  "baseDomain": "dev.local",
  "databasePrefix": "myproject",
  "caddyApi": "http://localhost:2019",
  "portRanges": {
    "api": {
      "start": 3000,
      "count": 1000
    },
    "web": {
      "start": 5000,
      "count": 1000
    },
    "spotlight": {
      "start": 7000,
      "count": 1000
    }
  },
  "envFiles": {
    "api": "packages/api/.env",
    "web": "packages/web/.env",
    "spotlight": "packages/spotlight/.env",
    "e2e": "packages/e2e/.env"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "",
    "templateDb": "myproject_dev"
  },
  "features": {
    "database": true,
    "spotlight": true,
    "queuePrefix": true
  },
  "integrations": {
    "mcp": true,
    "spotlight": true
  }
}

配置选项

核心设置

projectName (需要):您的项目名称,用于各种标识符
baseDomain (需要):用于通路的基域(如:, dev.local(中文(简体) )
databasePrefix (需要):数据库名称的前缀
caddyApi: Caddy Admin API 的 URL( 默认 ): http://localhost:2019(中文(简体) )

端口范围

定义每项服务的端口范围。港口根据工作树路径确定分配:

"portRanges": {
  "api": { "start": 3000, "count": 1000 },
  "web": { "start": 5000, "count": 1000 },
  "spotlight": { "start": 7000, "count": 1000 }
}

环境文件

指定相对于工程根的.env文件的路径 :

"envFiles": {
  "api": "packages/api/.env",
  "web": "packages/web/.env",
  "spotlight": "packages/spotlight/.env",
  "e2e": "packages/e2e/.env"
}

数据库配置

"database": {
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "password": "",
  "templateDb": "myproject_dev"
}

templateDb: 要克隆的新工作树的模板数据库

特征

启用或禁用特性 :

"features": {
  "database": true,      // PostgreSQL database per worktree
  "spotlight": true,     // Spotlight debugging integration
  "queuePrefix": true    // BullMQ queue prefix per worktree
}

一体化

"integrations": {
  "mcp": true,          // MCP configuration updates
  "spotlight": true     // Spotlight MCP server
}

图标

`devctl setup [name]`

设置有端口,数据库和凯迪路线的工作树.

# Use current branch name
devctl setup

# Use custom subdomain
devctl setup my-feature

# Use root domain instead of subdomain
devctl setup --root-domain

# Use custom config file
devctl setup -c /path/to/.devctlrc.json

它会做什么:

基于工作树路径生成独特的端口
从模板创建 PostgreSQL 数据库( 如果启用)
用端口和数据库 URL 更新.env 文件
配置凯迪反向代理路由
Claude 代码集成更新 .mcp.json
运行数据库迁移

`devctl list` 编号 : `devctl ls`

列出所有活动凯迪路线及其端口和工作树路径.

devctl list

`devctl remove <subdomain>` 编号 : `devctl rm <subdomain>`

删除特定子域的凯迪路由 .

devctl remove my-feature

`devctl ports <subdomain>`

获取特定子域的端口信息 .

devctl ports my-feature

`devctl init [project-name]`

创建一个 .devctlrc.json 当前目录中的配置文件 .

devctl init my-project

# Overwrite existing config
devctl init my-project --force

数据库命令

`devctl dump [database-name]`

将数据库丢入 SQL 文件 .

# Dump current worktree's database
devctl dump

# Dump specific database
devctl dump myproject_feature_branch

# Specify output file
devctl dump -o /path/to/backup.sql

`devctl restore <dump-file> [database-name]`

从 SQL 垃圾堆文件中恢复数据库 .

# Restore to current worktree's database
devctl restore backup.sql

# Restore to specific database
devctl restore backup.sql myproject_feature_branch

`devctl list-dumps`

列出可用的数据库堆放文件 .

devctl list-dumps

`devctl doctor`

检查环境和依赖性.

devctl doctor

检查 :

配置文件
Git 仓库状态
卡车可用性
PostgreSQL 工具

工作流程示例

设立新功能分支

# Create a new worktree
git worktree add ../my-feature feature/my-feature
cd ../my-feature

# Setup development environment
devctl setup

# Start your services
pnpm dev

您的特性分支现在可访问 https://my-feature.dev.local 改为:

孤立的 PostgreSQL 数据库
不相冲突的独特端口
凯迪路由配置
所有 .env 文件更新

与数据库合作

# Dump your main database for use in feature branches
cd /path/to/main-worktree
devctl dump

# In your feature worktree, restore from main
cd /path/to/feature-worktree
devctl restore myproject_main-2024-01-15T10-30-00.sql

清理

# Remove Caddy route when done
devctl remove my-feature

# Remove worktree
git worktree remove ../my-feature

# Optionally drop the database
dropdb myproject_my_feature

所需资源

节点.js: v18 或更高值
凯蒂: v2 已启用 Admin API
邮递SQL: 用于数据库特性(可选)
图形:用于检测工作树

凯迪设置

您的 Caddy 文件应该启用管理员 API :

{
  admin localhost:2019
}

或者使用 API 运行凯迪 :

caddy run --config Caddyfile

PostgreSQL 设置

对于数据库特性,请确保安装 PostgreSQL :

# macOS
brew install postgresql

# Or use Docker
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  pgvector/pgvector:pg16

如何运作

港口配置

端口使用工作树路径的 MD5 散列来决定性生成 :

修筑绝对的道路
转换前四个十六进制字符
在配置的端口区域开始后添加偏移
检查可用性, 如果被占用, 尝试下次抵消

这确保:

同一个工作树总是得到相同的端口( 如果有的话)
不同的工作树得到不同的端口
不需要人工港口管理

数据库隔离

每个工作树都有自己的PostgreSQL数据库:

创建数据库名称 : {prefix}_{sanitized_branch_name}
使用模板数据库中的克隆 CREATE DATABASE ... TEMPLATE
自动运行迁移
用新的 DATABASE URL 更新所有.env 文件

凯迪跑道

自动配置反向代理路由 :

https://feature-branch.dev.local/api/*  → localhost:3042 (API)
https://feature-branch.dev.local/*      → localhost:5042 (Web)
https://feature-branch.dev.local/_spotlight → localhost:7042 (Spotlight)

路由包括自定义有工作树元数据来调试.

解决问题

凯迪没有运行

# Check if Caddy is running
curl http://localhost:2019/config/

# Start Caddy
caddy run --config Caddyfile

未找到 PostgreSQL 工具

# macOS - Install PostgreSQL
brew install postgresql

# Or use the bundled tools from Postgres.app
export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

港口冲突

如果已经使用端口,devctl将尝试最多100个不同的抵消. 如果全部失败:

请检查date=中的日期值 (帮助) lsof -i :PORT
调整您的端口区域 .devctlrc.json
杀死相互冲突的进程

数据库连接出错

# Check PostgreSQL is running
psql -U postgres -h localhost -d postgres

# Verify template database exists
psql -U postgres -h localhost -d postgres -c "\l"

路线不工作

# Check Caddy configuration
curl http://localhost:2019/config/apps/http/servers/srv0/routes | jq

# List all routes
devctl list

# Run diagnostics
devctl doctor

发展

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Watch mode for development
pnpm build --watch

# Link for local testing
npm link

# Test in a project
cd /path/to/test/project
devctl setup

许可证

麻省理工学院

捐款

欢迎捐款! 请随意提交拉力请求.

版本与发布记录

@adamhancock/devctl2 共发布 9 个版本，首次发布于 2026/01/28；过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`1.1.4`latest	2026/08/31	2 个月前
`1.1.3`	2026/08/09	2 个月前
`1.1.2`	2026/08/09	2 个月前
`1.1.1`	2026/04/28	6 个月前
`1.1.0`	2026/04/28	6 个月前
`1.0.7`	2026/03/17	7 个月前

关于 @adamhancock/devctl2 的常见问题

@adamhancock/devctl2 是什么？

具有可配置应用程序、凯迪、数据库隔离和港口管理的多工作树项目通用开发环境管理员

如何安装 @adamhancock/devctl2？

在项目目录运行 npm install @adamhancock/devctl2，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 devctl2，可以用 npx devctl2 直接运行。

@adamhancock/devctl2 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@adamhancock/devctl2 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@adamhancock/devctl2 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@adamhancock/devctl2 可以商用吗？

@adamhancock/devctl2 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@adamhancock/devctl2 的下载量有多少？

根据 npm 官方下载统计，@adamhancock/devctl2 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,319 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@adamhancock/devctl2 还在维护吗？

最新版本 1.1.4 发布于 2026/08/31（2 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/01/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @adamhancock/devctl2

pnpmpnpm add @adamhancock/devctl2
yarnyarn add @adamhancock/devctl2
bunbun add @adamhancock/devctl2

命令行npx devctl2

在你的项目目录中运行此命令。

近 30 天下载

2,319

约 2319 次日均 77 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，2 天前更新

最新版本1.1.4发布于 2 个月前

开源许可MIT宽松许可

包体积188 kB40 个文件 · 解压后

运行依赖6 个

模块格式ES Module

TypeScript自带类型

Node.js>=18.0.0

发布版本9 个近 12 个月 9 个

首次发布2026/01/289 个月前

元数据更新2026/08/31

每一个软件包背后，
都有分享与创造的人。