lawless/docs/部署指南.md

# 洪荒大陆 - 文档站部署指南

> 文档站访问地址：`https://docs.xuqinmin.com`
> 部署服务器：`106.54.23.149`
> 最后更新：2026-07-03

---

## 一、域名边界

本项目现在把两个域名分工完全拆开：

| 域名 / 服务 | 归属 | 说明 |
|------|------|------|
| `win.xuqinmin.com` | **WSL** | 仅用于 WSL 的 SSH 连接和游戏服务端访问地址 |
| `docs.xuqinmin.com` | **106.54.23.149** | 仅用于文档站访问 |

> 结论：`win.xuqinmin.com` 不承载文档站；`docs.xuqinmin.com` 不承载 WSL 或游戏服务端连接。

---

## 二、文档站结构

文档站采用 MkDocs 生成，部署路径约定如下：

| 位置 | 用途 |
|------|------|
| `/var/www/docs.xuqinmin.com/site` | MkDocs 输出目录 |
| `/var/www/docs.xuqinmin.com/webroot` | Let's Encrypt HTTP-01 校验目录 |
| `/etc/nginx/sites-available/docs.xuqinmin.com.conf` | Nginx 站点配置 |

---

## 三、服务器首次配置

### 3.1 安装依赖

在 `106.54.23.149` 上安装：

- `nginx`
- `acme.sh`
- `rsync`

### 3.2 放置 Nginx 配置

将仓库中的 `nginx-docs.conf` 放到：

```text
/etc/nginx/sites-available/docs.xuqinmin.com.conf
```

然后创建站点目录：

```bash
sudo mkdir -p /var/www/docs.xuqinmin.com/site /var/www/docs.xuqinmin.com/webroot
```

### 3.3 申请 SSL 证书

使用 `acme.sh` 的 webroot 方式申请证书，并安装到统一目录：

```bash
~/.acme.sh/acme.sh \
  --issue \
  -d docs.xuqinmin.com \
  -w /var/www/docs.xuqinmin.com/webroot

~/.acme.sh/acme.sh \
  --install-cert \
  -d docs.xuqinmin.com \
  --ecc \
  --key-file /opt/xuqm/acme/docs.xuqinmin.com_ecc/docs.xuqinmin.com.key \
  --fullchain-file /opt/xuqm/acme/docs.xuqinmin.com_ecc/fullchain.cer \
  --reloadcmd "sudo systemctl reload nginx"
```

证书路径会落在：

```text
/opt/xuqm/acme/docs.xuqinmin.com_ecc/
```

### 3.4 自动续期

`acme.sh` 会自行维护续期任务；`--reloadcmd` 会在续期成功后重载 Nginx。仓库也保留了一个通用重载脚本 `deploy/docs/certbot-renew-hook.sh`。

---

## 四、自动更新

推荐在 `106.54.23.149` 上安装一个自动同步任务，执行入口建议使用仓库中的 `scripts/sync-docs-site.sh`。

仓库中的 `docs-build` 工作流负责构建校验；服务器上的自动同步任务会在 `main` 分支推送后自动：

1. 检出代码。
2. 安装 `mkdocs-material`。
3. 生成静态站点。
4. 同步到 `/var/www/docs.xuqinmin.com/site`。

---

## 五、本地开发

本地只负责改文档和预览，不直接改服务器：

```bash
make docs-build
make docs-serve
```

构建产物会输出到仓库根目录的 `site/`。

---

## 六、维护检查

### 6.1 检查站点

```bash
curl -I https://docs.xuqinmin.com
```

### 6.2 检查证书

```bash
ls -l /opt/xuqm/acme/docs.xuqinmin.com_ecc/
```

### 6.3 检查续期

```bash
~/.acme.sh/acme.sh --renew -d docs.xuqinmin.com --ecc --dry-run
```

---

*部署指南 v2.1 | 2026-07-03 | 文档站正式切换到 `docs.xuqinmin.com`，服务器为 `106.54.23.149`，并保留 SSL 自动续期和 push 自动更新方案*