OpenDeploy

面向单机、少量服务器场景的轻量部署框架，适合 Go、Rust、Deno 等单二进制项目；支持同一项目的多二进制服务（如核心服务 + 后台服务），所有服务共享一个远端部署目录（deploy_dir 必填）。

一条命令完成：构建 → 打包上传 → 原子替换 → systemd → health check；若项目自带 deploy/nginx.conf，还会同步上传并安全生效。

DNS 解析、tls证书这类根域名级、几乎不变的一次性配置，需要自行手动维护，不在本框架范围。

安装

npm i -g open-deployer

由于命名被占用，我们增加了一个er尾缀

命令

框架会注册opendeploy命令

# 用法，[项目路径]参数可选，缺省为当前目录。
    opendeploy init   [项目目录]
    opendeploy check  [项目目录]
    opendeploy deploy [-f|--force] [项目目录]
# 其他    
	opendeploy -h 
	opendeploy -v

deploy --force（或 -f）：即使 systemd unit/二进制哈希无变化，也强制覆盖 unit + daemon-reload + restart——适用于二进制未变但配置已变（如监听端口调整）需确定生效的场景。

init

生成 deploy/deploy.yaml 与 deploy/nginx.conf 模板，需要编辑 deploy/deploy.yaml，把 todo… 占位值改为真实值。

check

校验部署声明与前置环境

deploy

执行 8 步自动部署

部署声明

要求开发者在项目根目录下的deploy目录内声明部署需求。

标准配置

框架定义了几个标准的、写死固定路径的配置文件

• deploy/deploy.yaml必有，内容需要遵循配置schema。

• deploy/nginx.conf 可选——如果项目里放了这个文件，框架自动同步到服务器并安全生效，如果没放则该服务视为纯本地运行，跳过整个 nginx 步骤。内容完全由开发者手写，框架不校验业务逻辑，只做 nginx -t 语法校验。

非标配置

整个 deploy/ 目录都是部署覆盖范围，打包与远端覆盖对整个目录生效。

由于不同的服务所需要注入的配置是非标的，比如支付服务还有自己的config.yaml，还要配置各底层渠道的密钥文件等，因此，框架允许开发者在deploy目录下自由配置其他非标的配置文件和资源，只要命名不和标准配置文件冲突就行。

git忽略

⚠️建议始终 git 忽略 deploy/ 目录。标准 nginx.conf 与非标配置/密钥大多涉及安全参数，即便项目不是开源的、多实例复用的项目，也应该git忽略deploy/这个目录。

deploy.yaml

deploy/deploy.yaml 必选。采用多服务标准结构：顶层共享字段 ssh + deploy_dir（必填），服务逐个列到 services 列表，每个服务 name/build/port/health_path（+ 可选 args）。

ssh: wutuo                # 顶层共享：~/.ssh/config 主机别名（建议免密→部署全自动；密钥带口令/密码认证则部署时交互输入）
deploy_dir: /opt/asyncrouter   # 必填：所有服务共享的远端部署目录，必须是 / 开头的绝对路径
services:
  - name: asyncrouter    # 服务唯一标识 [A-Za-z0-9_-]+，派生二进制名、systemd/nginx 配置名
    build: go build -ldflags "-s -w" -o deploy/asyncrouter.new ./cmdx/core
    port: 4044                # 服务监听端口，仅用于本机 health check
    health_path: /v1/health   # 状态检查端点（默认 /v1/health，需以 / 开头，固定 3s 超时）
    args: --config /opt/asyncrouter/configs/config.yaml   # 可选：传给二进制的原始 argv
  - name: asyncrouter-admin   # 第二个服务
    build: go build -ldflags "-s -w" -o deploy/asyncrouter-admin.new ./cmdx/admin
    port: 4045
    health_path: /v1/health

• 单服务的项目把服务写在 services 列表第一项即可（列表长度 1），框架对所有项目一视同仁。

• args（可选）：传给二进制的原始 argv（不是 shell 命令）。默认无参启动——服务按自身"隐式协议"在部署目录同级找配置（如 openlitepay 默认读 config.yaml）；需要显式传参的项目（C++/Rust/Deno 常依赖 -c/--config）才填写，例如 args: -c /opt/openlitepay/app.toml --daemon。注意：这些参数由 systemd 直接 execve 传给二进制、不经过 shell——变量($VAR)、通配符(*)、重定向(>)、管道(|) 都不会展开/解释；若某个参数值含空格，请用引号包住（如 --name "my app"）。

• build 是完整 shell 命令，框架不二次封装；要求把产物输出到 deploy/{service}.new（框架对go有特殊照顾，会自动注入 GOOS=linux GOARCH=amd64 CGO_ENABLED=0 交叉编译环境，已有环境变量则沿用，所以命令里不需要手写 GOOS=linux 等前缀，直接写 go build -ldflags "-s -w" -o deploy/{service}.new ./cmd/server 即可）。

• 占位值检测：形如 todo… 的值会被视为未填，check/deploy 会报错阻止。

• 服务名与项目根目录名会做小写比对，不一致时以 ⚠️ 提示，避免串名测试（多服务时逐个比对）。

• services 列表会自动做服务名重复检查，同名服务会导致 systemd/nginx 配置互相覆盖，直接报错阻止。

• services 列表为空或缺失时，check/deploy 会报错"至少需要一个服务"，不会静默跳过。

• deploy_dir 必填且必须是以 / 开头的绝对路径，缺失或相对路径都会直接报错阻止。

nginx.conf

deploy/nginx.conf可选。

• 若项目有 deploy/nginx.conf，框架自动同步到 /etc/nginx/conf.d/{service}.conf 并安全生效（备份 → 原子替换 → nginx -t → reload；失败则回滚，不影响本次已成功的 binary/systemd 部署）。
• 内容完全由开发者手写（location、限流、CORS、超时等），框架不解析、不模板化。
• 未提供 nginx.conf 的服务视为纯本地运行，跳过整个 nginx 步骤。

部署流程

[1/8] 读取 + 校验 deploy.yaml（含占位符检测、服务名比对；多服务逐项校验 + 重名检查）
[2/8] 本地构建（多服务：逐个 build，逐个确认 deploy/{name}.new 产物存在）
[3/8] tar 打包 deploy/ 目录 → scp 上传到远端 /tmp/
[4/8] 远端部署目录就绪 + 解压 + 执行 deploy.sh
      · 所有服务共享 deploy_dir：mkdir -p /opt/{dir} 解压一次
[5/8] mv 原子替换二进制（同文件系统 rename）——每个服务各一次
[6/8] systemd：hash 比对，变更才更新 unit + daemon-reload，然后 restart——每个服务各一次（`deploy --force` 时跳过 hash 比对，无条件覆盖 unit + daemon-reload + restart，用于二进制未变但配置已变需确定生效的场景）
[7/8] health check：curl 127.0.0.1:{port}{health_path}，3s 超时，15 次重试——每个服务各一次
[8/8] 若存在 nginx.conf：备份 → 替换 → nginx -t → reload/回滚（单块，与 services 数量无关）

幂等：重复执行结果一致；systemd/nginx 配置无变化时不会重复替换/重载。

前置依赖

自动部署是否能通，对本地和linux服务器有某些系统级工具依赖，比如老版本或精简版 Windows 可能缺少 OpenSSH Client，请先安装再使用。

已知依赖工具。

| 命令 | 用途 | 平台说明 | | ---------------------------- | ----------------------------------- | ------------------------------------------------------ | | ssh / scp | 远程连接与上传 | Windows 10 1803+ 自带 OpenSSH Client；macOS/Linux 自带 | | tar | 打包上传（gz） | Windows 自带 bsdtar；Linux 建议 gzip 支持 | | go | 执行 build 命令编译 | 仅为示例；实际由 deploy.yaml 的 build 命令决定 | | curl / systemd / nginx | 远端 health check / 服务托管 / 反代 | 需在部署的服务器上就绪 |