返回技术笔记搭站笔记
DEPLOYMENT NOTES / 01

HTTPS 文档站

换服务器涉及的备份和恢复顺序记在云服务器迁移中,本文保留具体的安装与排障步骤;照片、文档的后续架构见存储与访问优化方案。

我想把散落在本地的学习笔记放到自己的服务器上,随时打开一个链接就能看。最初只是发布 HTML,后来又涉及端口、HTTPS、证书续期和内容更新。这篇就从一个链接怎样对应到文件开始,记录搭建时遇到的问题和后续维护方法。

整理于 2026-11-12Ubuntu 24.04 · Nginx实际核验:Certbot 5.8.0适用:公网 IPv4 + SSH

这篇记录使用的是 Ubuntu 24.04,其他系统的安装方式和目录可能不同。前六节整理首次搭建的步骤,第 7–9 节是后续更新和维护时会用到的内容。示例里的 YOUR_PUBLIC_IP 需要替换成实际公网 IPv4。

命令分为本地和服务器两部分:PowerShell 代码在本地电脑执行,其余在 SSH 登录后的服务器 Bash 中执行,修改系统文件时使用 root。已有服务的机器需要先备份并比较配置差异,再合并下面的示例。

01 · 先弄清楚:一个链接怎样找到文件

我这台服务器的 443 端口已经被 Xray 使用,所以把个人网站和文档放在 8443。访问链接也就要带上 :8443。这里需要区分:端口决定连接哪个服务,路径决定读取哪一份内容。Nginx 可以直接提供 HTML、CSS 和图片,这个文档站不需要额外运行应用后端。

浏览器 → TCP 8443HTTPS:个人网站和技术文档
可信证书验证服务器身份
Nginx → 静态目录/ → /var/www/chensj-home/
/docs/ → /var/www/docs/
Certbot → TCP 80HTTP-01 验证及后续续期
定时检查,成功更新后重载 Nginx
入口对应内容本站行为
https://IP:8443/个人网站首页导航包含「技术笔记」
https://IP:8443/docs/文档目录首页明确列出可阅读的文章
/docs/web-deployment/这篇文档站搭建笔记独立 HTML 页面
/docs/xray/Xray 搭建笔记保留原有文档入口
http://IP/.well-known/acme-challenge/…证书验证文件通过 80 端口读取,不能拦截
其他普通 HTTP 路径不提供正文返回 403,不自动跳转

目录映射也容易混淆:/docs/ 通过 alias 对应独立的 /var/www/docs/,URL 和磁盘目录都保留末尾斜杠。它与 root 拼接请求路径的方式不同。遇到 404 时,可以先对照“请求路径 → 实际文件”的对应关系,再查配置。具体规则见 Nginx alias 文档。

02 · 动手之前,给自己留一个恢复点

动手前,我先确认 SSH 还能正常登录、服务器时间正确,以及 80 和 8443 的监听与公网入口。在云控制台检查 TCP 80、8443 的入站允许规则;公开访问时 IPv4 来源为 0.0.0.0/0。如果主机防火墙也启用了,还要检查那一层。已有的 SSH 和 443 服务要继续可用,不能为了部署网页清空规则。

ssh root@YOUR_PUBLIC_IP
cat /etc/os-release
timedatectl status
ss -lntp
nginx -T

还没装 Nginx 的服务器上,最后一条命令会提示「command not found」。下面的备份与安装命令在同一个 root Bash 会话中执行;BACKUP_DIR 保存这次操作的恢复点,后面需要时可以找到它:

set -e
BACKUP_DIR="/root/web-docs-backup/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$BACKUP_DIR"
if [ -d /etc/nginx ]; then
  cp -a /etc/nginx "$BACKUP_DIR/nginx"
fi
for d in chensj-home docs; do
  if [ -d "/var/www/$d" ]; then
    cp -a "/var/www/$d" "$BACKUP_DIR/$d"
  fi
done
printf 'Backup: %s\n' "$BACKUP_DIR"
apt-get update
apt-get install -y nginx python3-venv ca-certificates curl
install -d -m 0755 /var/www/chensj-home /var/www/docs
install -d -m 0755 /var/www/letsencrypt/.well-known/acme-challenge

修改定时器或续期钩子时,原文件也要一并备份。项目文件和公开网页分开存放:网页目录只放需要展示的页面与静态资源,SSH 密钥、证书私钥、真实客户端配置和整个代码仓库都不放进去。

03 · 只用 HTTPS,为什么还要留 80 端口

我希望普通 HTTP 链接读不到正文,但证书验证还需要一个入口。这两件事可以分开配置:先在 /etc/nginx/sites-available/xray-guide 中准备下面这个 HTTP server 块,只让 ACME 验证路径提供文件。第一次申请时还没有证书,不能直接引用不存在的证书文件;已有站点则只合并缺少的部分。

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name YOUR_PUBLIC_IP;
    server_tokens off;
    charset utf-8;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/letsencrypt;
        default_type text/plain;
        try_files $uri =404;
    }
    location / {
        return 403;
    }
}

启用配置之前,先用 nginx -T 查看是否已有另一个 default_server。如果 Ubuntu 默认站点占用了相同监听端口,要先确认没有业务,再把它的启用链接移到备份目录。下面的命令只在目标链接不存在时创建它:

if [ ! -e /etc/nginx/sites-enabled/xray-guide ] && \
   [ ! -L /etc/nginx/sites-enabled/xray-guide ]; then
  ln -s /etc/nginx/sites-available/xray-guide /etc/nginx/sites-enabled/xray-guide
fi
nginx -t && systemctl reload nginx

如果 Nginx 尚未运行,语法检查通过后再执行 systemctl enable --now nginx。接下来我用一个不含敏感内容的小文件检查验证路径,比直接申请证书更容易看清文件映射是否正确:

# 服务器上;保留 PROBE 值用于验收与清理
PROBE="web-check-$(date +%s)"
printf 'acme-ok\n' > "/var/www/letsencrypt/.well-known/acme-challenge/$PROBE"
printf 'http://YOUR_PUBLIC_IP/.well-known/acme-challenge/%s\n' "$PROBE"

在另一台电脑上,用 PowerShell 执行 curl.exe --noproxy "*" http://YOUR_PUBLIC_IP/.well-known/acme-challenge/实际探针名,应得到 acme-ok。检查结束后,在刚才的服务器会话里删除这个探针:rm -- "/var/www/letsencrypt/.well-known/acme-challenge/$PROBE"。首页返回 403、验证路径能访问,是这里预期的两种行为。

04 · 没有域名,我怎样用上 HTTPS

我一开始也把域名、HTTPS 和端口联系在一起看。整理这次部署后,我记下了一个更清楚的区别:证书验证访问的身份,端口负责找到服务。这里使用 Let’s Encrypt 的 IP 地址证书,不必先买域名,签发免费。按这次核对的规则,IP 证书有效期约 6 天,Webroot 方式要求 Certbot 5.4 或更新版本;这意味着自动续期要一起考虑。具体依据是后面列出的官方说明。

这次环境里使用的是独立 Python 虚拟环境中的 Certbot 5.8.0,这里记录具体版本,便于复现。后续升级需单独测试,同时检查是否留下了重复的续期任务。

# 新环境安装;已有 /opt/certbot 时先检查版本
python3 -m venv /opt/certbot
/opt/certbot/bin/pip install 'certbot==5.8.0'
/opt/certbot/bin/certbot --version

正式申请前,先通过测试环境排查配置,减少重复签发。命令中的 --agree-tos 表示接受 CA 条款,运行前需要阅读并确认;--register-unsafely-without-email 表示不提交邮箱,需要登记时可换成 --email 实际邮箱。

/opt/certbot/bin/certbot certonly --dry-run \
  --webroot -w /var/www/letsencrypt \
  --preferred-challenges http --required-profile shortlived \
  --ip-address YOUR_PUBLIC_IP --cert-name xray-docs-ip \
  --non-interactive --agree-tos --register-unsafely-without-email

演练成功后,再去掉 --dry-run 申请可信证书。测试 CA 的证书不受普通浏览器信任,不能拿来作为正式站点证书。

/opt/certbot/bin/certbot certonly \
  --webroot -w /var/www/letsencrypt \
  --preferred-challenges http --required-profile shortlived \
  --ip-address YOUR_PUBLIC_IP --cert-name xray-docs-ip \
  --non-interactive --agree-tos --register-unsafely-without-email

openssl x509 -in /etc/letsencrypt/live/xray-docs-ip/fullchain.pem \
  -noout -dates -issuer -ext subjectAltName

拿到证书后,还需要检查 SAN 里是否包含实际公网 IP。Nginx 读取 fullchain.pem 和 privkey.pem;私钥留在受限目录里,不复制到网页目录。这里也能看出:证书对应的是 IP 身份,不是 8443 这个端口。

05 · 证书有了,再把页面接到 HTTPS

有了有效证书,才可以在同一站点配置里追加 HTTPS 的 server 块。第 3 节的 HTTP 验证入口继续保留。下面记录的是最小配置;我在已有站点上操作时,还要保留照片缓存等其他 location。

server {
    listen 8443 ssl;
    listen [::]:8443 ssl;
    server_name YOUR_PUBLIC_IP;
    server_tokens off;
    charset utf-8;

    ssl_certificate /etc/letsencrypt/live/xray-docs-ip/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/xray-docs-ip/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:DocsTLS:10m;
    ssl_session_timeout 1d;

    location /docs/ {
        alias /var/www/docs/;
        index index.html;
        autoindex off;
        add_header X-Content-Type-Options nosniff always;
        add_header Cache-Control "no-cache" always;
    }

    root /var/www/chensj-home;
    index index.html;
    autoindex off;
    location / {
        try_files $uri $uri/ =404;
        add_header X-Content-Type-Options nosniff always;
        add_header Cache-Control "no-cache" always;
    }
}
nginx -t && systemctl reload nginx
ss -lntp | grep -E ':(80|8443)\b'

我把首页放在 /var/www/chensj-home/index.html,文档目录页放在 /var/www/docs/index.html,每篇文章再有自己的子目录。导航使用 /docs/文章名/ 这样的同源路径,后续换域名或端口时,就不用逐个修改文章链接。

这里配置的“只用 HTTPS”是指普通 HTTP 请求看不到正文,所以当前返回 403,也不自动跳转。证书验证是单独保留的例外:ACME 路径仍通过 80 端口直接返回验证内容,不能跳到自定义的 8443 端口。以前只看浏览器最终打开了哪个页面,很容易忽略这两个入口的区别。这里附上 HTTP-01 规则。

06 · 证书会过期,续期之后还得加载

网页能打开以后,我还需要考虑几天之后会怎样。定时执行 renew 只是检查是否需要续期,不是每次都签发;成功更新后,Nginx 也要 reload 才会加载新证书。于是我把“定时检查”和“成功后重载”拆成两部分,后者由 deploy-hook 完成。依据见 Certbot 续期说明。

6.1 成功续期后的钩子

创建 /etc/letsencrypt/renewal-hooks/deploy/20-reload-docs-nginx:

#!/bin/sh
set -eu
/usr/sbin/nginx -t
/bin/systemctl reload nginx

赋予执行权限:chmod 0750 /etc/letsencrypt/renewal-hooks/deploy/20-reload-docs-nginx。若父目录不存在,先使用 install -d -m 0755 /etc/letsencrypt/renewal-hooks/deploy 创建。

6.2 systemd 服务

保存为 /etc/systemd/system/xray-docs-cert-renew.service:

[Unit]
Description=Renew the IP certificate for the documentation site
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/opt/certbot/bin/certbot renew --cert-name xray-docs-ip --quiet --no-random-sleep-on-renew
TimeoutStartSec=600

6.3 定时器

保存为 /etc/systemd/system/xray-docs-cert-renew.timer:

[Unit]
Description=Check documentation IP certificate renewal four times daily

[Timer]
OnCalendar=*-*-* 00,06,12,18:00:00 UTC
RandomizedDelaySec=1800
Persistent=true
Unit=xray-docs-cert-renew.service

[Install]
WantedBy=timers.target

这份定时器每天在 UTC 00、06、12、18 点检查,再附加 0–30 分钟随机延迟;换成北京时间是 08、14、20 点和次日 02 点。Persistent=true 的作用是补触发:补上停机期间错过的检查,但服务器关机时当然无法完成续期。

systemctl daemon-reload
systemctl enable --now xray-docs-cert-renew.timer
systemctl list-timers --all xray-docs-cert-renew.timer
/opt/certbot/bin/certbot renew --cert-name xray-docs-ip \
  --dry-run --run-deploy-hooks
systemctl start xray-docs-cert-renew.service
systemctl show xray-docs-cert-renew.service -p Result -p ExecMainStatus

测试时,--dry-run --run-deploy-hooks 会验证续期流程并运行重载钩子,不替换生产证书。判断结果要结合退出码和日志:nginx -t 的成功提示也会写到标准错误流,不能看到 “error output” 就判定失败。oneshot 服务执行完显示 inactive 也可能正常,关键是 Result=success 和退出码。

07 · 让更新笔记变成一件可重复的事

为了让这些笔记真正方便查阅,我把「技术笔记」放进首页导航,也保留独立的 /docs/ 目录页。文章页沿用网站的导航、字体和配色,既能从主页进入,也能收藏单篇链接。更新时,文件会经过下面几个位置:

# 仓库中的源文件和构建产物
source/technical-notes.json             # 标题、摘要、标签和日期
source/docs/web-deployment/index.html   # 本篇原稿
source/docs/xray/index.html             # Xray 指南原稿
scripts/build_docs.py                   # 生成目录并套用网站导航与阅读样式
scripts/build_site.py                   # 生成首页及技术笔记页签
dist/docs/                             # 可发布的文档文件

# 服务器映射
dist/index.html        → /var/www/chensj-home/index.html
dist/assets/           → /var/www/chensj-home/assets/
dist/docs/             → /var/www/docs/

发布时容易漏掉的一点是:Nginx 的 alias 读取独立的文档目录。只把 dist/docs/ 复制到网站根目录,并不会更新线上 /docs/。因此发布脚本分别处理网站和文档两个目标目录。

7.1 构建和检查

# 在本地仓库根目录执行
python -X utf8 scripts/build_site.py --contact-mode full
node --check dist/assets/resume.js
node tests/photo-viewer.cjs
python -X utf8 scripts/prepare_release.py

这里的 full 是我的网站当前使用的联系方式展示模式,仅展示邮箱则对应 email。构建会同时生成首页和文档,release/site/ 里保存待发布文件、校验清单和更新脚本。

7.2 上传并发布

上传前,我先在本地运行 python -m http.server 8765 --directory dist --bind 127.0.0.1,打开 http://127.0.0.1:8765/#notes 检查文章标题和链接。下面保留 Windows PowerShell 的上传写法,发布目录按时间区分:

$releaseId = Get-Date -Format 'yyyyMMdd-HHmmss'
ssh ali "mkdir -p /root/chensj-releases/$releaseId"
scp -r release/site/. "ali:/root/chensj-releases/$releaseId/"
ssh ali "python3 /root/chensj-releases/$releaseId/update_resume.py"

下面这段沿用早期阿里云服务器的发布方式。迁到 AWS 后使用 ubuntu 登录,需先上传到可写目录,再用 sudo 发布,并显式设置 SITE_HOST 为新地址;完整调整见迁移笔记。示例里的 ali 是 SSH 别名,要换成当前电脑已有的别名,或 root@YOUR_PUBLIC_IP。发布脚本先校验文件,再保留网站和文档的旧版本,更新后检查 HTTP/HTTPS 响应;失败时尝试恢复并保留现场。这里有一个限制:两个目录是依次切换的,不是一个跨目录的原子操作,适合在访问较少的时候更新。

页面发布与服务配置是两件事:只改 HTML、CSS、JavaScript 时,不需要重启或 reload Nginx;修改样式和脚本后则要更新资源版本参数。新增文章还需要同步维护目录数据和发布白名单,否则“本地能看到”不等于“线上已发布”。

08 · 页面打不开时怎么查

检查时分两步:先在服务器内部确认 Nginx 能正确返回页面,再从另一台电脑检查公网入口。下面的请求保留证书校验,不用 -k 跳过问题:

# 服务器本机:绕过公网路由,仍校验证书的 IP 身份
curl --noproxy '*' --resolve YOUR_PUBLIC_IP:8443:127.0.0.1 \
  -I https://YOUR_PUBLIC_IP:8443/docs/

# 服务器检查有效期与续期记录
openssl x509 -in /etc/letsencrypt/live/xray-docs-ip/fullchain.pem -noout -dates
systemctl list-timers --all xray-docs-cert-renew.timer
journalctl -u xray-docs-cert-renew.service --since '7 days ago' --no-pager
Test-NetConnection YOUR_PUBLIC_IP -Port 8443
curl.exe --noproxy "*" --connect-timeout 8 --max-time 20 -I https://YOUR_PUBLIC_IP:8443/
curl.exe --noproxy "*" --connect-timeout 8 --max-time 20 -I https://YOUR_PUBLIC_IP:8443/docs/
curl.exe --noproxy "*" --connect-timeout 8 --max-time 20 -I https://YOUR_PUBLIC_IP:8443/docs/web-deployment/
curl.exe --noproxy "*" --connect-timeout 8 --max-time 20 -I https://YOUR_PUBLIC_IP:8443/docs/xray/

这四个 HTTPS 地址都应返回 200,还需要在浏览器里检查导航、手机排版、代码复制和返回链接。HTTP 首页则应返回 403。页面今天能访问,只能说明当前请求成功;以后能否续期,还要看定时器、验证入口和日志。下表整理了常见现象及排查方向,部分作为以后遇到问题时的参考。

现象优先检查判断方法
8443 连接超时云防火墙、主机防火墙、监听端口本机 HTTPS 成功、公网 TCP 失败时,先查入站路径;此时尚未进行 TLS 握手。
证书不可信或过期是否为测试证书、完整证书链、IP SAN、时间检查 openssl 输出、续期日志与 deploy-hook;不要用跳过校验作为修复。
/docs/ 返回 403目录首页与读取权限关闭 autoindex 时需存在可读取的 index.html;还要确认是否误用了 HTTP。
文章返回 404alias 的路径及文件位置检查 /var/www/docs/文章名/index.html;确认 URL 大小写和末尾斜杠。
证书申请或续期失败80 端口、ACME 路径、定时任务日志8443 可访问并不代表 80 可用于验证。避免把验证请求跳转到 8443。
更新后页面仍旧目标目录和资源版本比较文件哈希,核对部署映射,再检查缓存;不要反复重启服务。

09 · 更新出错时,我怎样回到上一版

如果更新失败,我先找发布报告中的恢复点 /root/nginx-backups/chensj-resume-时间戳/。previous-homepage 和 previous-docs 分别保存上一版网站和文档。下面保留恢复命令作为备用;先确认时间戳,再把当前版本也留在备份目录,避免丢掉排查线索:

# root Bash;替换为发布报告中的实际路径,且只执行一次
set -e
BACKUP_DIR='/root/nginx-backups/chensj-resume-实际时间戳'
test -d "$BACKUP_DIR/previous-homepage"
test -d "$BACKUP_DIR/previous-docs"
test ! -e "$BACKUP_DIR/replaced-homepage"
test ! -e "$BACKUP_DIR/replaced-docs"
mv /var/www/chensj-home "$BACKUP_DIR/replaced-homepage"
mv "$BACKUP_DIR/previous-homepage" /var/www/chensj-home
mv /var/www/docs "$BACKUP_DIR/replaced-docs"
mv "$BACKUP_DIR/previous-docs" /var/www/docs

静态文件恢复后,重新执行第 8 节的检查,不必重载 Nginx。这里的目录移动只适用于已核实的同一服务器和目录结构,不能直接照搬到另一块磁盘或另一套部署。

如果改动的是 Nginx 配置,我需要恢复对应变更前的那一份,执行 nginx -t,通过后再 reload。早期只有 HTTP 的配置虽然也是备份,却未必适合现在的 HTTPS 站点,选择恢复点时要看清内容。

后续维护主要看三件事:看定时器最近是否成功执行;关注线上证书的剩余有效期,特别是不足两天时;修改防火墙、Nginx 或 Certbot 后再演练续期。当前定时器只负责续期,没有通知告警。需要查原因时,可以看 systemd journal 和 /var/log/letsencrypt/letsencrypt.log。

这次我最想记住的,是把端口、路径和证书分开理解。浏览器能打开一篇文章,只是请求链路跑通了;能持续访问,还依赖目录映射、自动续期、发布检查和可用的备份。后面我想继续补上证书到期提醒,让维护不只依靠自己记得去看。

10 · 这次记住了什么,以及参考资料

以上整理自这套文档站的部署,技术核验记录为 2026-11-12,文字更新于 2026-11-16。我还在学习这些组件之间的配合,软件版本和 CA 规则也会变化;以后迁移或升级时,会回到下面这些官方资料重新核对。

返回技术笔记