# @ai-development-environment/server 中文文档

规范地址：https://npmcn.com/package/%40ai-development-environment/server/

版本：0\.0\.145
npm 元数据更新时间：2026-11-06T18:24:02.447Z
中文译文更新时间：2026-11-06T07:21:40.050Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-development-environment/server
原文对照：https://npmcn.com/package/%40ai-development-environment/server/?lang=original
项目主页：https://github.com/bludesign/ai-development-environment#readme
源码仓库：https://github.com/bludesign/ai-development-environment

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

- 包体积（解压后）：172 MB，4268 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.16\.0 \<25
- 运行依赖：5 个
- 首次发布：2026-07-18T23:27:48.800Z
- 最新版本发布：2026-11-06T18:24:01.990Z
- 近 30 天下载量：4210（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：118（近 12 个月 118 个）

## 中文简介

AI 重点开发环境( 预建 Next.js 独立服务器)

## 安装

```sh
npm install @ai-development-environment/server
```

也可以使用：`pnpm add @ai-development-environment/server`、`yarn add @ai-development-environment/server`、`bun add @ai-development-environment/server`

## README

# @ai-development-environment/server (中文(简体) )

预建的 Next.js 独立服务器 [AI 发展环境](https://github.com/bludesign/ai-development-environment)。 。 。 .

## 安装

```bash
npm install -g @ai-development-environment/server
```

要求节点24(`>=24.16.0 <25`) (中文(简体) ).

## 运行

```bash
export APP_SECRET="$(openssl rand -base64 32)"
export APP_ORIGINS="http://127.0.0.1:3090"
ai-development-environment
```

命令应用等待数据库迁移,然后启动服务器 `http://127.0.0.1:3090` 与代理图形QL WebSockets 连接 `ws://127.0.0.1:3091/graphql`。将 SQLite 数据库存储于 `~/.ai-development-environment/production.db` 默认.

## 配置

覆盖环境变量 :

| 变量 | 默认 |
| --- | --- |
| `HOSTNAME` | `127.0.0.1` |
| `PORT` | `3090` |
| `AGENT_WS_HOSTNAME` | `127.0.0.1` |
| `AGENT_WS_PORT` | `3091` |
| `DATABASE_URL` | `file:~/.ai-development-environment/production.db` |
| `APP_SECRET` | 需要除 macOS 键链自动存储; 基数64 或 十六进制 完全 32 字节 |
| `APP_SECRET_PREVIOUS` | 未设置; 仅在旋转时设置 `APP_SECRET` |
| `APP_ORIGINS` | 未设置; 从每个请求的主机推断 |
| `TRUST_PROXY_HEADERS` | `false` |
| `MCP_OAUTH_ENABLED` | `false` |
| `MCP_OAUTH_DCR_ENABLED` | `false` |
| `AUTH_MODE` | `password` |
| `CREDENTIAL_STORAGE_TYPE` | `database` |
| `VAULT_ADDR` | 断层需要 |
| `VAULT_TOKEN` | 未设定 |
| `VAULT_NAMESPACE` | 未设定 |
| `CREDENTIAL_VAULT_MOUNT` | `secret` |
| `CREDENTIAL_VAULT_PATH_PREFIX` | `ai-development-environment/credentials` |
| `CREDENTIAL_VAULT_HEADERS` | `{}` |
| `VAULT_CACERT` | 未设定 |
| `VAULT_TLS_SERVER_NAME` | 未设定 |
| `VAULT_SKIP_VERIFY` | `false` |
| `CREDENTIAL_VAULT_READ_ONLY` | `false` |

只读 SQLite `file:` 支持为 `DATABASE_URL`。 。 。 .

对于数据库或虚拟存储,生成 `APP_SECRET` 一次与 `openssl rand -base64 32`,备份,并保持稳定 跨升级。 它必须是完全32个随机字节的base64或hex编码——密码句被拒绝,因为会话签名,数据库证书加密,安装-链接签名都是由此而来. 更改它会让每个人退出 并取消未完成的安装链接 。 对于数据库证书,通过旧值为 `APP_SECRET_PREVIOUS` 可以在下次启动时重新加密它们;一旦服务器开始干净,就删除它们。 密钥链和断层证书并不依赖于这个秘密.

在macOS上与 `CREDENTIAL_STORAGE_TYPE=keychain`离开 `APP_SECRET` 未设置或空白以使用自动存储 。 开始服务前, 服务器读取服务 `com.bludesign.ai-development-environment.app-secret`账户 `APP_SECRET`从您的登录键链。 如果没有输入,它会产生并坚持一个32字节的秘密. 在同一macOS账户下的每一台服务器安装都通过重启和升级来共享. 明确的环境价值总是优先的,必须仍然有效,并且永远不能被复制到键链中。 没有秘密被写入环境文件 。 Homebrew 公式已经选择了 keychain 存储; npm 和源安装必须明确选择它.

备份键链条目 。 删除一个环境覆盖到存储或新生成的密钥链根的开关,并可能使现有会话和签名链接失效。 锁定、 无法访问或畸形的条目停止启动而不是替换密钥: 解锁您的登录密钥链并允许访问、 恢复原始条目或供应 `APP_SECRET` 当然 初始化使用临时锁定 `~/.ai-development-environment/`; 并行开始等至30秒后,废弃锁会自动失效. 如果无法获取锁, 请检查目录权限并重试 。 构建从不访问键链. 自动存储只在macOS上可用.

`APP_ORIGINS` 是可选的逗号分隔的服务器来源列表 。 本地主机在生产之外总是值得信赖. 离开它和 `PUBLIC_BASE_URL` 未设置使服务器信任每个请求 `Host`,这意味着它所产生的绝对URL会跟随呼叫者所要求的任何主机.

第一个登记申请的账户关闭公共登记。 然后每个账户都有完全一样的权威:任何登录的用户都可以创建和删除账户,设置任何人的密码,取消会话,并发布API密钥. 没有角色.

`AUTH_MODE` 接受 `password`, (中文(简体) ), `oidc`,或 `both`. OIDC模式需要通用提供者客户端ID和秘密,并需要发现URL或完整的授权,令牌,以及用户-info端点设置. 见 [认证文件](https://ai-development-environment.mintlify.app/reference/authentication) 全体会议 `AUTH_OAUTH_*` 变量列表并重定向 URL.

即将到来的MCP OAuth独立于 `AUTH_MODE` 并默认禁用。 设置条子 HTTPS `PUBLIC_BASE_URL` (或 `APP_ORIGINS`),部署迁移,然后设定 `MCP_OAUTH_ENABLED=true`. CIMD 默认识别客户端; 启用 `MCP_OAUTH_DCR_ENABLED=true` 仅针对需要动态注册的老年客户。 OAuth 访问仅限于 `/api/mcp`,有单独的读取,写取,破坏性同意. 管理撤销在 **设置 ~ 已连接的应用程序**现有课程、API密钥和注册代理继续工作。 见 [MCP OAuth 设置和推出指南](https://ai-development-environment.mintlify.app/reference/mcp-oauth)。 。 。 .

### 证书后端

`CREDENTIAL_STORAGE_TYPE` 接受 `database`, (中文(简体) ), `vault`,或 `keychain`。数据库是 npm 、 Linux 和 Docker 的默认值。 数据库秘密总是用从 `APP_SECRET`;没有纯文本模式,也没有单独的加密密钥可以配置. 在加密成为无条件之前所写的行在下一个开始时会被加密. 旋转被支持: 将旧根设置为 `APP_SECRET_PREVIOUS` 并存储的证书在启动时重新加密。 Vault 和 keychain 存储完全不使用衍生密钥 .

默认只支持 KV v2 。 引用自定义标题 JSON 作为一个 shell 值, 例如 `CREDENTIAL_VAULT_HEADERS='{"X-Vault-AWS-IAM-Server-ID":"vault.example.com"}'`。标准符号/名称空间变量不能与等同的自定义标题相冲突. `VAULT_CACERT` 必须是服务器进程可以读取的。 平面文本默认 HTTP 和 `VAULT_SKIP_VERIFY=true` 工作但显示突出的拦截警告。 默认前缀政策是:

```hcl
path "secret/data/ai-development-environment/credentials/*" {
  capabilities = ["create", "read", "update"]
}
path "secret/metadata/ai-development-environment/credentials/*" {
  capabilities = ["list", "delete"]
}
```

`list` 是可选的。 有了它,一个服务器在前缀下发现了每个证书,包括每个服务器的MCP头包和APN证书;没有它,发现仍然覆盖了存储在固定路径上的每个证书.

### 在新安装上重用已存在的默认

一个服务器指向一个已经持有证书的 Vault 在它开始的时候通过它们: 它读取所配置的挂载和前缀下存储的内容并重建描述它的本地元数据行. 无需重新输入,全权证书页报告了通过的项目数量。 先前后端下记录的这种安装的证书被同样采用,因为配置后端是读取所能达到的唯一一个:一旦确认Vault持有这个秘密,本地行被重新指向Vault,被取代的数据库副本被从中去掉. 在 Vault - 非秘密设置中, 如Jira 站点 URL 或 GitHub App ID 等, 只有秘密存在。 仍然在每次安装时输入 。 第二点安装在同一挂载和前缀上,它们共享一组秘密,它们之间没有协调;其中之一的书写立即可见于另一个.

因为Vault标志是唯一的标志,所以把它当作证书:任何能在Vault上指出新安装的人都会得到一个工作安装.

### 仅读默认安装

`CREDENTIAL_VAULT_READ_ONLY=true` 声明一个安装决不能写给 Vault 。 秘密字段在设置表单中变为只读,在发出任何请求之前拒绝证书写和删除;非秘密设置仍然可以编辑. 该设置仅适用于下列情况: `CREDENTIAL_STORAGE_TYPE=vault`——数据库和密钥链存储忽略了它,并在"证书"页面上报告警告. 仅仅缺乏写出能力的一个符号不需要这个旗帜: Vault 的拒绝被报告为相同的只读错误而不是赤裸的 HTTP 403. 只读安装需求 :

```hcl
path "secret/data/ai-development-environment/credentials/*" {
  capabilities = ["read"]
}
path "secret/metadata/ai-development-environment/credentials/*" {
  capabilities = ["read", "list"]
}
```

macOS keychain 仅动态地加载到达尔文上;在 Linux 或 Docker 报告时选择一个错误而不崩溃应用程序 。 不要将密钥链支持的服务运行为根 。 切换存储后端从不复制一个值到新的后端. 切换到服务器可以读回内容的"沃特"(Vault),继续为每个已持有的秘密"沃特"(Vault)工作;所配置的后端不持有的任何内容都会被作为不匹配内容在"全权证书委员会"(Capital)页面上报告,并且必须通过自己的设置形式重新进入. 外部后端断电只会影响依赖证书的特性.

## 另见

-   [`@ai-development-environment/control-agent`](https://www.npmjs.com/package/@ai-development-environment/control-agent) ——被管理的机器的控制剂.
-   这个 [土生土长水龙头](https://github.com/bludesign/homebrew-ai-development-environment) ——将服务器运行为 `brew services` 守护进程 .

## 常见问题

### @ai-development-environment/server 是什么？

AI 重点开发环境\( 预建 Next\.js 独立服务器\)

### 如何安装 @ai-development-environment/server？

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

### @ai-development-environment/server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ai-development-environment\_\_server 是否存在。

### @ai-development-environment/server 需要什么版本的 Node\.js？

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

### @ai-development-environment/server 可以商用吗？

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

### @ai-development-environment/server 的下载量有多少？

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

### @ai-development-environment/server 还在维护吗？

最新版本 0\.0\.145 发布于 2026/11/07（1 天前）；至今共发布 118 个版本，其中过去 12 个月发布了 118 个；首次发布于 2026/07/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。