# 部署与运维记录

> 记录服务器环境、部署流程与上线状态。凭据不写入本文件。

## 服务器信息

- 系统：Ubuntu 26（全新）
- 域名：shizhui.xyz（已解析，可 ping 通）
- 登录：建议改用 SSH 密钥，关闭 root 密码登录（待办）

## 部署架构

```
本地构建 (npm run build) → 生成 dist/ 静态文件
  → rsync/scp 上传到服务器 /var/www/shizhui
  → Nginx 托管
  → Let's Encrypt 提供 HTTPS
```

采用"本地构建 + 上传 dist"的方式，服务器无需安装 Node，最简单、最稳定。

## 一、服务器初始化（首次）

```bash
# 更新系统
apt update && apt upgrade -y

# 安装 Nginx 与 certbot
apt install -y nginx certbot python3-certbot-nginx

# 防火墙放行 HTTP/HTTPS/SSH
ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw --force enable

# 站点目录
mkdir -p /var/www/shizhui
```

## 二、Nginx 配置

文件：`/etc/nginx/sites-available/shizhui`（仓库内见 `deploy/nginx-shizhui.conf`）

```bash
ln -sf /etc/nginx/sites-available/shizhui /etc/nginx/sites-enabled/shizhui
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx
```

## 三、申请 HTTPS 证书

```bash
certbot --nginx -d shizhui.xyz -d www.shizhui.xyz
# 自动续期已由 certbot 的 systemd timer 处理，可验证：
certbot renew --dry-run
```

## 四、发布更新（每次内容/代码变更后）

本地执行（见 `deploy/deploy.sh`）：

```bash
npm run build
rsync -avz --delete dist/ root@shizhui.xyz:/var/www/shizhui/
```

## 五、上线检查清单

- [x] 服务器初始化完成（swap 2G + Nginx 1.28 + certbot 4.0 + ufw 防火墙）
- [x] Nginx 配置就位并 reload
- [x] 首次上传 dist（服务器本机 HTTP 200 正常）
- [x] 阿里云安全组放行 80（之前规则未应用到实例，已修复，80/8080 探测 open）
- [x] HTTP 公网访问正常（http://shizhui.xyz → 200）
- [x] 阿里云安全组放行 443
- [x] HTTPS 证书申请成功（DNS-01 验证，含 shizhui.xyz/www/git，到期 2026-09-09，自动续期已配）
- [x] HTTPS 配置启用（本机握手 200，HTTP 跳转 HTTPS）
- [ ] 浏览器访问 https://shizhui.xyz 正常（**需先完成 ICP 备案**，否则被劫持）
- [ ] 清理临时 8080 测试配置（备案上线后）
- [ ] 更换 root 密码 + 配置 SSH 密钥登录
- [ ] 备案完成后轮转阿里云 AccessKey

## 排障记录：公网端口不通

现象：服务器内部 nginx/ufw 全正常，本机 HTTP 200，但公网探测 80 closed、
nginx 日志无任何外部请求。

排查：用服务器调用第三方端口探测服务（ports.yougetsignal.com）从外部探测，
并对比高位端口 8080。最终定位为**阿里云安全组规则未应用到实例**（实例绑定的
安全组与编辑的安全组不一致）。修正绑定后 80/8080 探测变为 open，HTTP 恢复正常。

结论：与备案、与本地 VPN 均无关，是安全组绑定问题。

## 排障记录：HTTPS 证书 HTTP 验证失败 (403 / 200空响应)

现象：80/443 端口已放行，静态文件外部访问完全正常（probe 文件本机/公网/www
三种方式均 200 且内容正确），但 certbot 的 ACME HTTP-01 验证始终失败：
Let's Encrypt 访问 `/.well-known/acme-challenge/<token>` 返回 403 或 200 空响应。

排查：
- webroot 与 nginx 插件两种方式都试过，均失败。
- 手动放置同目录静态文件（testfile/probe123），本机、公网 IP、www Host
  三种请求都正常返回 200 + 正确内容。
- certbot 写入的 challenge 文件路径与内容均正确（已边写边抓验证）。
- 域名解析 IP 与服务器真实公网 IP 一致，未走 CDN。
- 唯一失败的是「瞬时新建的 acme-challenge 路径」被外部访问时异常。

判断：阿里云网络入口对突发的 `/.well-known/acme-challenge/` 新路径存在安全
拦截（国内服务器常见），导致 HTTP-01 验证不可用。

### 真正根因：域名未备案（已确认）

通过外部代理对比确认：
- `http://shizhui.xyz/`（域名+80）→ 返回阿里云劫持页
  `<title>Non-compliance ICP Filing</title>`（未备案提示），我们的网站被拦截。
- `http://8.137.165.96:8080/`（IP+非标端口）→ 正常返回站点。

阿里云对**未备案域名**经标准端口（80/443）的访问会劫持到备案提示页，
这正是 HTTP-01 验证拿到 403/异常响应的真正原因。

影响与对策：
- **HTTPS 证书**：HTTP 验证不可用，改用 **DNS-01 验证**（阿里云 DNS 插件，已安装
  certbot-dns-aliyun 2.0.0）。
- **域名正式可用前必须完成 ICP 备案**。备案前域名走 80/443 一律被劫持。
- **测试访问地址**（备案完成前）：`http://8.137.165.96:8080/`

解决方案：改用 **DNS-01 验证**签发证书，绕开 80 端口。
- 方案一（采用）：阿里云 DNS 插件 + RAM 子账号 AccessKey（只给 DNS 权限），
  全自动签发与续期。