{"_id":"@aaricchen1991/deploy","_rev":"2-20860a4c9059eedb1b164184e633908e","name":"@aaricchen1991/deploy","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"@aaricchen1991/deploy","version":"0.1.0","_id":"@aaricchen1991/deploy@0.1.0","maintainers":[{"name":"aaricchen1991","email":"aaricchen@gmail.com"}],"bin":{"n2-deploy":"dist/cli.js"},"dist":{"shasum":"0fb6ea4451936df412934d2e61908c843f99243a","tarball":"https://registry.npmjs.org/@aaricchen1991/deploy/-/deploy-0.1.0.tgz","fileCount":49,"integrity":"sha512-Zrt3SPhSE4CaEyqB3b+GrfsymRb7lDonbPhqM1SVqqzGl1a+RxgTWhlA2Kss0ukRtOpPjZrBNldWSVbsIG5ejw==","signatures":[{"sig":"MEUCIQCXvmc7NvoSzKq5pEoc68OYf3JVHYqJ2rb8+LzpuQGn7QIgBzXt0DQYfs7aQV9X68O+T1VZpgjjsbdF1zegXfXja0k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95911},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"0121e3826a65cd75586967be5d1b2395b204c697","scripts":{"cli":"node dist/cli.js","dev":"tsc && node dist/cli.js","build":"tsc"},"_npmUser":{"name":"aaricchen1991","email":"aaricchen@gmail.com"},"_npmVersion":"10.9.4","description":"CLI for server init, nginx config, and SSL certificate management","directories":{},"_nodeVersion":"22.21.1","dependencies":{"commander":"^12.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"~5.9.3","@types/node":"^25.0.3"},"_npmOperationalInternal":{"tmp":"tmp/deploy_0.1.0_1770696842478_0.6955798021993189","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aaricchen1991/deploy","version":"1.0.0","description":"CLI for server init, nginx config, and SSL certificate management","type":"module","bin":{"n2-deploy":"dist/cli.js"},"scripts":{"build":"tsc","cli":"node dist/cli.js","dev":"tsc && node dist/cli.js"},"dependencies":{"commander":"^12.1.0","consola":"^3.4.2"},"devDependencies":{"@types/node":"^25.0.3","typescript":"~5.9.3"},"engines":{"node":">=20.0.0"},"_id":"@aaricchen1991/deploy@1.0.0","gitHead":"e49eaf5ee5bfa435994534f86fd4873eaa43f7e7","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-ETAj0FtF1060dCXAC/gIDpHFX3+i+ekJXt8mt2z4f8Ax5xKTj2V1KypUSi5hm3zkbcOBq9xfv1u1UHMeHpQoQA==","shasum":"484d12c5d397dcc51de23678ef2df1edf5199494","tarball":"https://registry.npmjs.org/@aaricchen1991/deploy/-/deploy-1.0.0.tgz","fileCount":59,"unpackedSize":148512,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDszK6abr06mby+vx7VBa/Xs7/5we7sEWCXVTomDmpc1AIhAKJJmnmHVD3WtShmDr9CMPLmrSLeqtddZFYcB/Wua2y0"}]},"_npmUser":{"name":"aaricchen1991","email":"aaricchen@gmail.com"},"directories":{},"maintainers":[{"name":"aaricchen1991","email":"aaricchen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/deploy_1.0.0_1770699533767_0.3158407446667335"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-10T04:14:02.416Z","modified":"2026-02-10T04:58:54.031Z","0.1.0":"2026-02-10T04:14:02.619Z","1.0.0":"2026-02-10T04:58:53.938Z"},"description":"CLI for server init, nginx config, and SSL certificate management","maintainers":[{"name":"aaricchen1991","email":"aaricchen@gmail.com"}],"readme":"# @aaricchen1991/deploy\n\n服务器部署与运维 CLI（包名 `@aaricchen1991/deploy`，命令 `n2-deploy`）：服务器初始化、Nginx 配置生成、SSL 证书申请/续期及日志查看。设计为在**部署服务器上**执行（或从本机指定配置生成文件）。\n\n## 功能概览\n\n| 命令 / 子命令 | 说明                                                                                 |\n| -------------- | ------------------------------------------------------------------------------------ |\n| `config`       | 配置管理：初始化、查看、设置、删除配置项（见下方「配置管理」）。                       |\n| `init`         | 服务器初始化（幂等）：安装 Nginx、创建目录、安装 `deploy.sh`、占位证书。可重复执行。   |\n| `nginx`        | 根据域名配置文件生成 Nginx 配置；可选安装到系统并 reload。                             |\n| `ssl`          | 为配置中的全部域名申请/续期 SSL 证书（acme.sh + 阿里云 DNS），并写入统一日志。         |\n| `ssl-logs`     | 查看 SSL 操作日志（创建、续期、成功、失败），支持行数、跟随、按动作/结果过滤。         |\n\n## 安装\n\n### 从本仓库使用\n\n在仓库根目录：\n\n```bash\npnpm install\npnpm --filter @aaricchen1991/deploy build\n```\n\n执行时默认从 **~/.deploy/config.yaml** 读取配置（含阿里云凭证与域名），也可通过 `-c, --config` 指定路径：\n\n```bash\nnode apps/deploy/dist/cli.js <command> [options]\n```\n\n或使用根目录脚本（会先构建再执行）：\n\n```bash\npnpm run deploy:cli -- <command> [options]\n```\n\n### 发布为 npm 包后\n\n```bash\nnpx @aaricchen1991/deploy --help\n```\n\n（安装后执行的命令仍为 `n2-deploy`，与包名 `@aaricchen1991/deploy` 对应。）\n\n如何将本包发布到 npm，见 [PUBLISHING.md](./PUBLISHING.md)。\n\n## 配置文件\n\n所有命令默认从 **~/.deploy/config.yaml** 读取配置。该文件可包含阿里云凭证（用于 `ssl` 命令）与域名配置，格式与仓库内 `scripts/deploy/domains.yaml` 兼容。**后端与前端同域**：各应用域名下 `/api` 由 Nginx 反向代理到后端，不再为 API 单独配置域名与 SSL。\n\n**示例 ~/.deploy/config.yaml：**\n\n```yaml\n# 可选：阿里云 Access Key（用于 ssl 命令申请/续期证书）\naliyun_access_key_id: \"your_key\"\naliyun_access_key_secret: \"your_secret\"\n\napi:\n  backend_port: 3000\n\nadmin:\n  domains:\n    - n2-admin.example.com\n\ntenant:\n  domains:\n    - n2-tenant.example.com\n\nclient:\n  domains:\n    - n2-client.example.com\n```\n\n- `aliyun_access_key_id` / `aliyun_access_key_secret`：可选；未设置时 `ssl` 命令会使用环境变量或 `--ali-key` / `--ali-secret`。\n- `api.backend_port`：API 后端端口（各应用域名下 `location /api` 的代理目标）。\n- 各应用的 `domains`：该应用对外提供服务的域名列表；**仅这些域名会申请 SSL 证书**。\n- 生产环境前端默认请求**同域 `/api`**（如 `n2-admin.example.com/api`），与 Nginx 的 `location /api` 一致，无需额外配置；可经 `VITE_API_BASE_URL` 覆盖。\n\n默认路径为 `~/.deploy/config.yaml`，可通过 `-c, --config <path>` 指定其它路径（支持 `~` 展开为用户目录）。\n\n### 配置管理（config）\n\n| 子命令   | 说明 |\n| -------- | ---- |\n| `config init` | 初始化配置文件（创建默认模板）。`-f, --force` 覆盖已存在文件。 |\n| `config list` | 列出所有配置项。 |\n| `config get [key]` | 查看单个配置项；不传 `key` 则列出全部。 |\n| `config set <key> [values...]` | 设置配置项。`domains` 类可传多个值，如：`config set admin.domains a.com b.com`。 |\n| `config delete <key>` | 删除/清空配置项（domains 清空列表，密钥置空）。 |\n\n支持的配置项 key：`aliyun_access_key_id`、`aliyun_access_key_secret`、`api.backend_port`、`api.domains`、`admin.domains`、`tenant.domains`、`client.domains`。  \n使用自定义配置文件时可在父命令或子命令上指定 `-c`，例如：`n2-deploy config -c ./config.yaml init` 或 `n2-deploy config init -c ./config.yaml`。\n\n---\n\n## 命令说明\n\n### init — 服务器初始化\n\n在部署服务器上执行（建议使用 root 或 sudo），完成：\n\n- 检测系统（Alibaba Cloud Linux / CentOS / Ubuntu 等）并安装 Nginx（若未安装）\n- 创建 `/var/www/{admin,tenant,client}`、`/opt/deploy`、`/etc/nginx/ssl` 等目录\n- 将 `deploy.sh` 安装到 `/opt/deploy/`\n- 根据 domains 配置生成占位 SSL 证书与 Nginx 配置并安装，使 Nginx 可正常启动\n\n**用法：**\n\n```bash\nn2-deploy init [options]\n```\n\n| 选项                   | 默认值                  | 说明                                                        |\n| ---------------------- | ----------------------- | ----------------------------------------------------------- |\n| `-c, --config <path>`  | `~/.deploy/config.yaml` | 部署配置文件路径（含域名与可选阿里云凭证）                  |\n| `--scripts-dir <path>` | 见下方                  | 部署脚本目录（含 deploy.sh、server-setup.sh、ssl/_、lib/_） |\n\n**脚本目录解析顺序：**\n\n1. 环境变量 `N2_DEPLOY_SCRIPTS_DIR`\n2. 当前目录下的 `scripts/deploy`（在仓库根目录执行时）\n3. 包内 `assets/deploy`（若存在）\n\n**示例：**\n\n```bash\n# 使用默认配置 ~/.deploy/config.yaml\nn2-deploy init\n\n# 指定配置文件与脚本目录（例如在服务器上单独拷贝了脚本）\nsudo n2-deploy init --config /etc/n2/config.yaml --scripts-dir /opt/n2-scripts\n```\n\n---\n\n### nginx — 生成/安装 Nginx 配置\n\n根据 domains 配置生成 `n2.conf`（API 反向代理 + 各前端静态站点 + HTTP 跳 HTTPS），可仅生成文件或同时安装到系统并 reload。\n\n**用法：**\n\n```bash\nn2-deploy nginx [options]\n```\n\n| 选项                  | 默认值                  | 说明                                                               |\n| --------------------- | ----------------------- | ------------------------------------------------------------------ |\n| `-c, --config <path>` | `~/.deploy/config.yaml` | 部署配置文件路径                                                   |\n| `-o, --output <path>` | `nginx/n2.conf`         | 生成的配置文件输出路径                                             |\n| `-i, --install`       | —                       | 安装到系统 Nginx 目录并执行 `nginx -t` 与 `systemctl reload nginx` |\n\n**示例：**\n\n```bash\n# 使用默认配置，仅生成到当前目录\nn2-deploy nginx --output ./n2.conf\n\n# 生成并安装到系统（需在服务器上且有相应权限）\nsudo n2-deploy nginx --config ~/.deploy/config.yaml --install\n```\n\n---\n\n### ssl — SSL 证书申请/续期\n\n为 domains 配置中的**所有域名**申请或续期证书（Let's Encrypt，通过 acme.sh + 阿里云 DNS API），安装到 `/etc/nginx/ssl/` 并触发 Nginx reload。所有操作会写入 SSL 专用日志，便于排查与审计。\n\n**用法：**\n\n```bash\nn2-deploy ssl [options]\n```\n\n| 选项                    | 默认值                     | 说明                     |\n| ----------------------- | -------------------------- | ------------------------ |\n| `-c, --config <path>`   | `~/.deploy/config.yaml`    | 部署配置文件路径         |\n| `--ali-key <key>`       | 见下方                     | 阿里云 Access Key ID     |\n| `--ali-secret <secret>` | 见下方                     | 阿里云 Access Key Secret |\n| `--log-file <path>`     | `/opt/deploy/logs/ssl.log` | SSL 日志文件路径         |\n| `--scripts-dir <path>`  | 同 init                    | 部署脚本目录             |\n\n**凭证来源（按优先级）：**  \n`--ali-key` / `--ali-secret` → 配置文件中的 `aliyun_access_key_id` / `aliyun_access_key_secret` → 环境变量 `ALIYUN_ACCESS_KEY_ID` / `ALIYUN_ACCESS_KEY_SECRET` → 环境变量 `Ali_Key` / `Ali_Secret`。\n\n**示例：**\n\n```bash\n# 使用默认 ~/.deploy/config.yaml（其中可配置 aliyun_access_key_id / aliyun_access_key_secret）\nsudo n2-deploy ssl\n\n# 使用环境变量覆盖\nexport ALIYUN_ACCESS_KEY_ID=\"your_key\"\nexport ALIYUN_ACCESS_KEY_SECRET=\"your_secret\"\nsudo n2-deploy ssl\n\n# 指定配置文件\nsudo n2-deploy ssl --config /etc/n2/config.yaml\n```\n\n**说明：**\n\n- 首次使用前需在服务器上执行过 `init`，或已手动将 SSL 相关脚本安装到 `/opt/ssl/`（如 `check-and-setup-ssl.sh`）。\n- 证书会安装到 `/etc/nginx/ssl/<domain>.crt` 与 `<domain>.key`，Nginx 配置中已引用该路径。\n- 建议通过 cron 或 systemd timer 定期执行 `n2-deploy ssl` 以实现自动续期。\n\n---\n\n### ssl-logs — 查看 SSL 日志\n\n查看 SSL 操作日志（创建、续期、成功、失败等）。日志为文本格式，部分行为结构化行（制表符分隔：时间、类型、域名、结果、消息）。\n\n**用法：**\n\n```bash\nn2-deploy ssl-logs [options]\n```\n\n| 选项                | 默认值                     | 说明                                                           |\n| ------------------- | -------------------------- | -------------------------------------------------------------- |\n| `--log-file <path>` | `/opt/deploy/logs/ssl.log` | SSL 日志文件路径                                               |\n| `-n, --lines <n>`   | `50`                       | 显示最后 N 行                                                  |\n| `-f, --follow`      | —                          | 持续跟踪（等同 `tail -f`）                                     |\n| `--action <action>` | —                          | 按动作过滤：`create` / `renew` / `success` / `failure` / `run` |\n| `--result <result>` | —                          | 按结果过滤：`ok` / `fail`                                      |\n\n**示例：**\n\n```bash\n# 查看最后 50 行\nn2-deploy ssl-logs\n\n# 查看最后 200 行并只显示失败\nn2-deploy ssl-logs --lines 200 --result fail\n\n# 实时跟踪\nn2-deploy ssl-logs --follow\n```\n\n---\n\n## 环境变量\n\n| 变量                                      | 说明                                                                                                           |\n| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| `N2_DEPLOY_SCRIPTS_DIR`                   | 部署脚本根目录（含 deploy.sh、server-setup.sh、ssl/、lib/）。未设置时使用 `cwd/scripts/deploy` 或包内 assets。 |\n| `ALIYUN_ACCESS_KEY_ID` / `Ali_Key`        | 阿里云 Access Key ID（ssl 命令）；也可写在 ~/.deploy/config.yaml 的 `aliyun_access_key_id`）。                 |\n| `ALIYUN_ACCESS_KEY_SECRET` / `Ali_Secret` | 阿里云 Access Key Secret（ssl 命令）；也可写在 ~/.deploy/config.yaml 的 `aliyun_access_key_secret`）。         |\n\n## 典型流程\n\n1. **首次部署服务器**\n   - 将本仓库或 `scripts/deploy` 拷贝到服务器（或设置 `N2_DEPLOY_SCRIPTS_DIR`）。\n   - 在服务器或本机创建 `~/.deploy/config.yaml`，填入域名与（可选）阿里云 `aliyun_access_key_id` / `aliyun_access_key_secret`。\n   - 执行：`sudo n2-deploy init`（默认读取 ~/.deploy/config.yaml）。\n   - 执行：`sudo n2-deploy ssl` 申请证书（凭证可从配置文件或环境变量读取）。\n   - 之后由 CI 通过 SSH 执行 `/opt/deploy/deploy.sh` 完成应用部署。\n\n2. **仅更新 Nginx 配置（如新增域名）**\n   - 修改 `~/.deploy/config.yaml` 后执行：  \n     `sudo n2-deploy nginx --install`\n   - 若新增了域名，再执行一次 `n2-deploy ssl` 为新域名申请证书。\n\n3. **定期续期证书**\n   - 使用 cron：例如每月执行一次  \n     `0 3 1 * * /usr/bin/n2-deploy ssl`\n   - 或使用 systemd timer 调用同一命令。\n\n4. **排查 SSL 问题**\n   - `n2-deploy ssl-logs --result fail` 查看失败记录。\n   - `n2-deploy ssl-logs --follow` 在再次执行 `ssl` 时实时查看输出。\n\n## 与 CI/CD 的关系\n\n- **GitHub Actions** 只负责构建产物（API 镜像、前端 tar）并部署到服务器（SSH + `/opt/deploy/deploy.sh`）。\n- **服务器环境与 SSL** 不在此流程中完成，需在服务器上预先执行 `n2-deploy init` 与 `n2-deploy ssl`（或等价的手动/脚本步骤）。\n\n详见仓库根目录 [docs/deployment.md](../../docs/deployment.md)。\n","readmeFilename":"README.md"}