@aaricchen1991/deploy

服务器部署与运维 CLI（包名 @aaricchen1991/deploy，命令 n2-deploy）：服务器初始化、Nginx 配置生成、SSL 证书申请/续期及日志查看。设计为在部署服务器上执行（或从本机指定配置生成文件）。

功能概览

| 命令 / 子命令 | 说明 | | -------------- | ------------------------------------------------------------------------------------ | | config | 配置管理：初始化、查看、设置、删除配置项（见下方「配置管理」）。 | | init | 服务器初始化（幂等）：安装 Nginx、创建目录、安装 deploy.sh、占位证书。可重复执行。 | | nginx | 根据域名配置文件生成 Nginx 配置；可选安装到系统并 reload。 | | ssl | 为配置中的全部域名申请/续期 SSL 证书（acme.sh + 阿里云 DNS），并写入统一日志。 | | ssl-logs | 查看 SSL 操作日志（创建、续期、成功、失败），支持行数、跟随、按动作/结果过滤。 |

安装

从本仓库使用

在仓库根目录：

pnpm install
pnpm --filter @aaricchen1991/deploy build

执行时默认从 ~/.deploy/config.yaml 读取配置（含阿里云凭证与域名），也可通过 -c, --config 指定路径：

node apps/deploy/dist/cli.js <command> [options]

或使用根目录脚本（会先构建再执行）：

pnpm run deploy:cli -- <command> [options]

发布为 npm 包后

npx @aaricchen1991/deploy --help

（安装后执行的命令仍为 n2-deploy，与包名 @aaricchen1991/deploy 对应。）

如何将本包发布到 npm，见 PUBLISHING.md。

配置文件

所有命令默认从 ~/.deploy/config.yaml 读取配置。该文件可包含阿里云凭证（用于 ssl 命令）与域名配置，格式与仓库内 scripts/deploy/domains.yaml 兼容。后端与前端同域：各应用域名下 /api 由 Nginx 反向代理到后端，不再为 API 单独配置域名与 SSL。

示例 ~/.deploy/config.yaml：

# 可选：阿里云 Access Key（用于 ssl 命令申请/续期证书）
aliyun_access_key_id: "your_key"
aliyun_access_key_secret: "your_secret"

api:
  backend_port: 3000

admin:
  domains:
    - n2-admin.example.com

tenant:
  domains:
    - n2-tenant.example.com

client:
  domains:
    - n2-client.example.com

• aliyun_access_key_id / aliyun_access_key_secret：可选；未设置时 ssl 命令会使用环境变量或 --ali-key / --ali-secret。
• api.backend_port：API 后端端口（各应用域名下 location /api 的代理目标）。
• 各应用的 domains：该应用对外提供服务的域名列表；仅这些域名会申请 SSL 证书。
• 生产环境前端默认请求同域 /api（如 n2-admin.example.com/api），与 Nginx 的 location /api 一致，无需额外配置；可经 VITE_API_BASE_URL 覆盖。

默认路径为 ~/.deploy/config.yaml，可通过 -c, --config <path> 指定其它路径（支持 ~ 展开为用户目录）。

配置管理（config）

| 子命令 | 说明 | | -------- | ---- | | config init | 初始化配置文件（创建默认模板）。-f, --force 覆盖已存在文件。 | | config list | 列出所有配置项。 | | config get [key] | 查看单个配置项；不传 key 则列出全部。 | | config set <key> [values...] | 设置配置项。domains 类可传多个值，如：config set admin.domains a.com b.com。 | | config delete <key> | 删除/清空配置项（domains 清空列表，密钥置空）。 |

支持的配置项 key：aliyun_access_key_id、aliyun_access_key_secret、api.backend_port、api.domains、admin.domains、tenant.domains、client.domains。
使用自定义配置文件时可在父命令或子命令上指定 -c，例如：n2-deploy config -c ./config.yaml init 或 n2-deploy config init -c ./config.yaml。

命令说明

init — 服务器初始化

在部署服务器上执行（建议使用 root 或 sudo），完成：

• 检测系统（Alibaba Cloud Linux / CentOS / Ubuntu 等）并安装 Nginx（若未安装）
• 创建 /var/www/{admin,tenant,client}、/opt/deploy、/etc/nginx/ssl 等目录
• 将 deploy.sh 安装到 /opt/deploy/
• 根据 domains 配置生成占位 SSL 证书与 Nginx 配置并安装，使 Nginx 可正常启动

用法：

n2-deploy init [options]

| 选项 | 默认值 | 说明 | | ---------------------- | ----------------------- | ----------------------------------------------------------- | | -c, --config <path> | ~/.deploy/config.yaml | 部署配置文件路径（含域名与可选阿里云凭证） | | --scripts-dir <path> | 见下方 | 部署脚本目录（含 deploy.sh、server-setup.sh、ssl/、lib/） |

脚本目录解析顺序：

1. 环境变量 N2_DEPLOY_SCRIPTS_DIR
2. 当前目录下的 scripts/deploy（在仓库根目录执行时）
3. 包内 assets/deploy（若存在）

示例：

# 使用默认配置 ~/.deploy/config.yaml
n2-deploy init

# 指定配置文件与脚本目录（例如在服务器上单独拷贝了脚本）
sudo n2-deploy init --config /etc/n2/config.yaml --scripts-dir /opt/n2-scripts

nginx — 生成/安装 Nginx 配置

根据 domains 配置生成 n2.conf（API 反向代理 + 各前端静态站点 + HTTP 跳 HTTPS），可仅生成文件或同时安装到系统并 reload。

用法：

n2-deploy nginx [options]

| 选项 | 默认值 | 说明 | | --------------------- | ----------------------- | ------------------------------------------------------------------ | | -c, --config <path> | ~/.deploy/config.yaml | 部署配置文件路径 | | -o, --output <path> | nginx/n2.conf | 生成的配置文件输出路径 | | -i, --install | — | 安装到系统 Nginx 目录并执行 nginx -t 与 systemctl reload nginx |

示例：

# 使用默认配置，仅生成到当前目录
n2-deploy nginx --output ./n2.conf

# 生成并安装到系统（需在服务器上且有相应权限）
sudo n2-deploy nginx --config ~/.deploy/config.yaml --install

ssl — SSL 证书申请/续期

为 domains 配置中的所有域名申请或续期证书（Let's Encrypt，通过 acme.sh + 阿里云 DNS API），安装到 /etc/nginx/ssl/ 并触发 Nginx reload。所有操作会写入 SSL 专用日志，便于排查与审计。

用法：

n2-deploy ssl [options]

| 选项 | 默认值 | 说明 | | ----------------------- | -------------------------- | ------------------------ | | -c, --config <path> | ~/.deploy/config.yaml | 部署配置文件路径 | | --ali-key <key> | 见下方 | 阿里云 Access Key ID | | --ali-secret <secret> | 见下方 | 阿里云 Access Key Secret | | --log-file <path> | /opt/deploy/logs/ssl.log | SSL 日志文件路径 | | --scripts-dir <path> | 同 init | 部署脚本目录 |

凭证来源（按优先级）：
--ali-key / --ali-secret → 配置文件中的 aliyun_access_key_id / aliyun_access_key_secret → 环境变量 ALIYUN_ACCESS_KEY_ID / ALIYUN_ACCESS_KEY_SECRET → 环境变量 Ali_Key / Ali_Secret。

示例：

# 使用默认 ~/.deploy/config.yaml（其中可配置 aliyun_access_key_id / aliyun_access_key_secret）
sudo n2-deploy ssl

# 使用环境变量覆盖
export ALIYUN_ACCESS_KEY_ID="your_key"
export ALIYUN_ACCESS_KEY_SECRET="your_secret"
sudo n2-deploy ssl

# 指定配置文件
sudo n2-deploy ssl --config /etc/n2/config.yaml

说明：

• 首次使用前需在服务器上执行过 init，或已手动将 SSL 相关脚本安装到 /opt/ssl/（如 check-and-setup-ssl.sh）。
• 证书会安装到 /etc/nginx/ssl/<domain>.crt 与 <domain>.key，Nginx 配置中已引用该路径。
• 建议通过 cron 或 systemd timer 定期执行 n2-deploy ssl 以实现自动续期。

ssl-logs — 查看 SSL 日志

查看 SSL 操作日志（创建、续期、成功、失败等）。日志为文本格式，部分行为结构化行（制表符分隔：时间、类型、域名、结果、消息）。

用法：

n2-deploy ssl-logs [options]

| 选项 | 默认值 | 说明 | | ------------------- | -------------------------- | -------------------------------------------------------------- | | --log-file <path> | /opt/deploy/logs/ssl.log | SSL 日志文件路径 | | -n, --lines <n> | 50 | 显示最后 N 行 | | -f, --follow | — | 持续跟踪（等同 tail -f） | | --action <action> | — | 按动作过滤：create / renew / success / failure / run | | --result <result> | — | 按结果过滤：ok / fail |

示例：

# 查看最后 50 行
n2-deploy ssl-logs

# 查看最后 200 行并只显示失败
n2-deploy ssl-logs --lines 200 --result fail

# 实时跟踪
n2-deploy ssl-logs --follow

环境变量

| 变量 | 说明 | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | N2_DEPLOY_SCRIPTS_DIR | 部署脚本根目录（含 deploy.sh、server-setup.sh、ssl/、lib/）。未设置时使用 cwd/scripts/deploy 或包内 assets。 | | ALIYUN_ACCESS_KEY_ID / Ali_Key | 阿里云 Access Key ID（ssl 命令）；也可写在 ~/.deploy/config.yaml 的 aliyun_access_key_id）。 | | ALIYUN_ACCESS_KEY_SECRET / Ali_Secret | 阿里云 Access Key Secret（ssl 命令）；也可写在 ~/.deploy/config.yaml 的 aliyun_access_key_secret）。 |

典型流程

1. 首次部署服务器

   • 将本仓库或 scripts/deploy 拷贝到服务器（或设置 N2_DEPLOY_SCRIPTS_DIR）。
   • 在服务器或本机创建 ~/.deploy/config.yaml，填入域名与（可选）阿里云 aliyun_access_key_id / aliyun_access_key_secret。
   • 执行：sudo n2-deploy init（默认读取 ~/.deploy/config.yaml）。
   • 执行：sudo n2-deploy ssl 申请证书（凭证可从配置文件或环境变量读取）。
   • 之后由 CI 通过 SSH 执行 /opt/deploy/deploy.sh 完成应用部署。

2. 仅更新 Nginx 配置（如新增域名）

   • 修改 ~/.deploy/config.yaml 后执行：
     sudo n2-deploy nginx --install
   • 若新增了域名，再执行一次 n2-deploy ssl 为新域名申请证书。

3. 定期续期证书

   • 使用 cron：例如每月执行一次
     0 3 1 * * /usr/bin/n2-deploy ssl
   • 或使用 systemd timer 调用同一命令。

4. 排查 SSL 问题

   • n2-deploy ssl-logs --result fail 查看失败记录。
   • n2-deploy ssl-logs --follow 在再次执行 ssl 时实时查看输出。

与 CI/CD 的关系

• GitHub Actions 只负责构建产物（API 镜像、前端 tar）并部署到服务器（SSH + /opt/deploy/deploy.sh）。
• 服务器环境与 SSL 不在此流程中完成，需在服务器上预先执行 n2-deploy init 与 n2-deploy ssl（或等价的手动/脚本步骤）。

详见仓库根目录 docs/deployment.md。