@ai-development-environment/server (中文(简体) )
预建的 Next.js 独立服务器 AI 发展环境。 。 。 .
安装
npm install -g @ai-development-environment/server
要求节点24(>=24.16.0 <25) (中文(简体) ).
运行
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端点设置. 见 认证文件 全体会议 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 设置和推出指南。 。 。 .
证书后端
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 工作但显示突出的拦截警告。 默认前缀政策是:
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. 只读安装需求 :
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——被管理的机器的控制剂.- 这个 土生土长水龙头 ——将服务器运行为
brew services守护进程 .