跳到主要内容

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

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

一、域名边界​

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

域名 / 服务归属说明
win.xuqinmin.comWSL仅用于 WSL 的 SSH 连接和游戏服务端访问地址
docs.xuqinmin.com106.54.23.149仅用于文档站访问

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

二、文档站结构​

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

位置用途
/var/www/docs.xuqinmin.com/siteMkDocs 输出目录
/var/www/docs.xuqinmin.com/webrootLet's Encrypt HTTP-01 校验目录
/etc/nginx/sites-available/docs.xuqinmin.com.confNginx 站点配置

三、服务器首次配置​

3.1 安装依赖​

在 106.54.23.149 上安装：

  • nginx
  • acme.sh
  • rsync

3.2 放置 Nginx 配置​

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

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

然后创建站点目录：

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

3.3 申请 SSL 证书​

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

~/.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"

证书路径会落在：

/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。

五、本地开发​

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

make docs-build
make docs-serve

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

六、维护检查​

6.1 检查站点​

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

6.2 检查证书​

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

6.3 检查续期​

~/.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 自动更新方案