# @adamhancock/devctl2 中文文档

规范地址：https://npmcn.com/package/%40adamhancock/devctl2/

版本：1\.1\.4
npm 元数据更新时间：2026-08-31T13:52:24.386Z
中文译文更新时间：2026-11-06T21:32:46.332Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adamhancock/devctl2
原文对照：https://npmcn.com/package/%40adamhancock/devctl2/?lang=original
项目主页：https://github.com/adamhancock/cli#readme
源码仓库：https://github.com/adamhancock/cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：188 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：6 个
- 首次发布：2026-01-28T14:19:18.400Z
- 最新版本发布：2026-08-31T13:52:23.968Z
- 近 30 天下载量：2319（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

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

## 安装

```sh
npm install @adamhancock/devctl2
```

也可以使用：`pnpm add @adamhancock/devctl2`、`yarn add @adamhancock/devctl2`、`bun add @adamhancock/devctl2`

## README

# 脱钩

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

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

## 特征

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

## 安装

### 地方发展

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Link globally for local testing
npm link
```

### 从npm起(已公布)

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

## 快速启动

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

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

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

```bash
cd /path/to/your/worktree
devctl setup
```

## 配置

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

### 示例配置

```json
{
  "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`(中文(简体) )

#### 端口范围

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

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

#### 环境文件

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

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

#### 数据库配置

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

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

#### 特征

启用或禁用特性 :

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

#### 一体化

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

## 图标

### `devctl setup [name]`

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

```bash
# 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
```

**它会做什么:**

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

### `devctl list` 编号 : `devctl ls`

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

```bash
devctl list
```

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

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

```bash
devctl remove my-feature
```

### `devctl ports <subdomain>`

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

```bash
devctl ports my-feature
```

### `devctl init [project-name]`

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

```bash
devctl init my-project

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

### 数据库命令

#### `devctl dump [database-name]`

将数据库丢入 SQL 文件 .

```bash
# 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 垃圾堆文件中恢复数据库 .

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

# Restore to specific database
devctl restore backup.sql myproject_feature_branch
```

#### `devctl list-dumps`

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

```bash
devctl list-dumps
```

### `devctl doctor`

检查环境和依赖性.

```bash
devctl doctor
```

检查 :

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

## 工作流程示例

### 设立新功能分支

```bash
# 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 文件更新

### 与数据库合作

```bash
# 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
```

### 清理

```bash
# 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 :

```caddyfile
{
  admin localhost:2019
}
```

或者使用 API 运行凯迪 :

```bash
caddy run --config Caddyfile
```

### PostgreSQL 设置

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

```bash
# macOS
brew install postgresql

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

## 如何运作

### 港口配置

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

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

这确保:

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

### 数据库隔离

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

1.  创建数据库名称 : `{prefix}_{sanitized_branch_name}`
2.  使用模板数据库中的克隆 `CREATE DATABASE ... TEMPLATE`
3.  自动运行迁移
4.  用新的 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)
```

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

## 解决问题

### 凯迪没有运行

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

# Start Caddy
caddy run --config Caddyfile
```

### 未找到 PostgreSQL 工具

```bash
# 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个不同的抵消. 如果全部失败:

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

### 数据库连接出错

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

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

### 路线不工作

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

# List all routes
devctl list

# Run diagnostics
devctl doctor
```

## 发展

```bash
# 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 是什么？

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

### 如何安装 @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 和提交记录判断。