# 域名部署（从 shadiao-2d 搬入）

> VOKO 说明：`environments/voko-alpha.json` 是**草案**，假设 Alpha 与 Visual Game Stage 共用 `52.33.173.48` 这台主机（独立目录 `/srv/voko-alpha`、独立 PM2 进程、独立数据库）。主机与数据库方案确认前不要执行。公开 API 域名 `api.voko.world`（`/v1` 前缀）需要在 `visual-game-nginx.js` 里增加对应 location，W5 部署前完成。

## 原文


本目录负责把一组 Visual Game 域名部署到指定服务器。部署入口统一使用 Node.js，完成 GoDaddy
DNS、Nginx、Let's Encrypt 证书和真实 HTTPS 验证。

## 目录结构

```text
infra/domains/
├── .env                         # GoDaddy PAT，本地密钥，不提交
├── deploy.js                    # 统一部署入口
├── godaddy-dns.js               # GoDaddy v3 DNS 写入
├── visual-game-nginx.js         # Visual Game Nginx 配置生成
└── environments/
    ├── visual-game-stage-voko.json
    └── visual-game-stage-voko-standard.json
```

环境差异只写在 `environments/*.json`。DNS、Nginx 和证书流程禁止复制到环境专用脚本。

## 配置 GoDaddy 凭据

打开 <https://developer.godaddy.com/personal-access-token>，创建 Personal Access Token：

1. Name 填写 `visual-game-dns-deploy`。
2. Expiration 选择可接受的有效期。
3. Scopes 只选择 `domains.domain:read` 和 `domains.dns:update`。
4. Token 生成后立即复制；GoDaddy 不会再次显示该值。

在 `infra/domains/.env` 写入：

```dotenv
GODADDY_PAT=<完整 Token>
```

执行：

```bash
chmod 600 infra/domains/.env
```

`.env` 已被仓库根 `.gitignore` 忽略。禁止把 Token 写进环境 JSON、服务器应用配置、命令参数或提交记录。

## 部署 Stage Voko 域名

在仓库根目录执行：

```bash
node infra/domains/deploy.js infra/domains/environments/visual-game-stage-voko.json
```

该环境配置对应：

- 玩家端：`https://game.voko.world`
- Admin：`https://admin-game.voko.world`
- Studio：`https://studio-game.voko.world`
- 服务器：`52.33.173.48`

Stage 规范域名使用独立环境配置：

- 玩家端：`https://stage-game.voko.world`
- Admin：`https://admin-stage-game.voko.world`
- Studio：`https://studio-stage-game.voko.world`

部署命令：

```bash
node infra/domains/deploy.js infra/domains/environments/visual-game-stage-voko-standard.json
```

脚本按以下顺序执行：

1. GoDaddy A 记录与目标 IP 一致时保持不变；不一致时替换为环境配置中的 IP。
2. 在目标服务器安装仅支持 HTTP 和 ACME challenge 的 Nginx 配置。
3. 使用服务器现有 acme.sh 为三个域名签发同一张证书。
4. 把证书安装到环境配置指定的稳定目录，并登记 Nginx reload 命令。
5. 安装 HTTPS Nginx 配置并 reload Nginx。
6. 真实访问三个 HTTPS 首页和玩家端 `/healthz`；任一响应不是 200 时部署失败。

脚本失败后直接退出，不回滚已经成功的 DNS 记录。修复错误后重新执行同一条命令；已经正确的 DNS
记录会显示为 `kept`，acme.sh 会继续使用已经登记的证书状态。

## 新增其他环境

复制现有环境配置：

```bash
cp infra/domains/environments/visual-game-stage-voko.json \
  infra/domains/environments/<新环境>.json
```

必须修改以下配置：

- `environment`：环境名称。
- `public_ip`：三个 A 记录指向的公网 IP。
- `ssh`：服务器地址、用户和本机 SSH 私钥。
- `application_root`：服务器当前 release 的稳定软链接。
- `backend_origin`：Nginx 代理的 Visual Game API 地址。
- `dns.zone`：GoDaddy 托管的根域名。
- `domains`：game、admin、studio 的完整域名、DNS record name 和前端 dist 目录。
- `nginx.site_name`：服务器上的独立 Nginx site 名称。
- `nginx.root_variable`：该 site 独占的 Nginx map 变量名。
- `nginx.certificate_directory`：该域名组独占的证书安装目录。
- `nginx.acme_webroot`：HTTP-01 challenge 目录。

目标服务器必须已经安装并运行 Nginx、acme.sh 和 Visual Game，且公网 80、443 端口可访问。
域名必须使用 GoDaddy 权威 Nameserver，否则 GoDaddy API 中的记录不会参与公网解析。

修改完成后执行：

```bash
node infra/domains/deploy.js infra/domains/environments/<新环境>.json
```

部署完成的判定标准是脚本输出三个 `HTTPS 200`、一个 `API 200` 和 `域名部署完成`。

## 证书续签

`deploy.js` 使用 acme.sh 的 `--install-cert` 保存证书安装路径和 `systemctl reload nginx`。服务器的
acme.sh 定时任务进入续签窗口后会重新签发证书、覆盖稳定路径中的 `key.pem` 与 `fullchain.pem`，随后
reload Nginx。Nginx 禁止直接读取 acme.sh 内部证书目录。