Files

CI / verify (push) Has been cancelled

Details

- 详情页路由入参统一为 stopId，废弃 targetType/targetId
- ExplainDetailEntryRequest 与 GlobalAudioSource 移除 targetType/targetId 字段
- 播放器源匹配仅按 stopId 判定，移除 targetType 兜底
- 删除 explainDetailTarget 死代码
- 清理 guideStopInfoAdapter 中 stop/info、play-info、text-info 旧契约类型与转换函数
- 补充测试服务器 Nginx SSL 部署手册
- 同步更新单测与 e2e 用例

Made-with: Proma

2026-09-17 11:30:32 +08:00

12 KiB

Raw Blame History

zjsjgjyyzx.cn 主站 HTTPS 与校验文件部署操作手册

最后更新：2026-09-07

1. 适用范围

本文档适用于腾讯云测试服务器上的主站域名 zjsjgjyyzx.cn，涵盖：

Let’s Encrypt SSL 证书申请与部署
保留 HTTP 80 和 HTTPS 443 的独立访问能力
Certbot 自动续期、证书同步和 Nginx reload
域名根目录 TXT 校验文件发布
配置验证与回滚

本文档不适用于导览 H5 站点 guide.whaoyue.com:8888/4433。该导览站点使用独立容器 sgs-nature-nginx，其部署手册见：

docs/deployment/guide-test-server-nginx-ssl.md

2. 当前部署目标与拓扑

项目	当前值
域名	`zjsjgjyyzx.cn`
服务器公网 IP	`124.220.83.186`
HTTP 地址	`http://zjsjgjyyzx.cn/`
HTTPS 地址	`https://zjsjgjyyzx.cn/`
主 Nginx 容器	`nginx`
Nginx 镜像	`nginx:latest`
Docker 网络	`bridge`
宿主机端口映射	`80 -> 80`、`443 -> 443`

请求链路：

HTTP 用户  -> zjsjgjyyzx.cn:80  -> nginx Docker 容器 -> 后台主站
HTTPS 用户 -> zjsjgjyyzx.cn:443 -> nginx Docker 容器 -> 后台主站

当前要求是 HTTP 和 HTTPS 均可直接访问。不要在 HTTP server 中配置强制跳转到 HTTPS，除非业务要求变更且完成专项验证。

3. 关键目录与文件

3.1 Nginx

宿主机路径	容器路径	用途
`/data/nginx/conf/nginx.conf`	`/etc/nginx/nginx.conf`	Nginx 主配置
`/data/nginx/conf/conf.d/`	`/etc/nginx/conf.d/`	站点配置目录
`/data/nginx/html/`	`/usr/share/nginx/html/`	静态资源根目录
`/data/nginx/html/admin-ui/`	`/usr/share/nginx/html/admin-ui/`	主站前端根目录
`/data/nginx/ssl/`	`/etc/nginx/ssl/`	Nginx 可读取的证书目录
`/data/nginx/logs/`	`/var/log/nginx/`	Nginx 日志

主站 HTTP 配置：

/data/nginx/conf/conf.d/zhjzpt.conf

主站 HTTPS 配置：

/data/nginx/conf/conf.d/zhjzpt-ssl.conf

3.2 证书

Certbot 管理的原始证书：

/etc/letsencrypt/live/zjsjgjyyzx.cn/fullchain.pem
/etc/letsencrypt/live/zjsjgjyyzx.cn/privkey.pem

Nginx 容器读取的同步副本：

/data/nginx/ssl/zjsjgjyyzx.cn/fullchain.pem
/data/nginx/ssl/zjsjgjyyzx.cn/privkey.pem

权限要求：

fullchain.pem: 0644
privkey.pem:   0600

3.3 自动续期 Hook

/etc/letsencrypt/renewal-hooks/deploy/zjsjgjyyzx.cn-nginx.sh

该 Hook 在证书续期成功后执行以下操作：

将证书复制到 /data/nginx/ssl/zjsjgjyyzx.cn/。
设置证书与私钥的安全权限。
执行 docker exec nginx nginx -t。
执行 docker exec nginx nginx -s reload。

4. 部署前检查

4.1 DNS 与备案

域名 A 记录必须统一指向：

zjsjgjyyzx.cn -> 124.220.83.186

至少使用多个公共 DNS 核对：

for r in 8.8.8.8 1.1.1.1 223.5.5.5 119.29.29.29; do
  printf "$r A="
  nslookup -type=A zjsjgjyyzx.cn "$r" 2>/dev/null |
    awk '/Address: /{print $2}' | tail -1
done

如使用阿里云 DNS，可检查权威记录：

dig +short A zjsjgjyyzx.cn @dns9.hichina.com
dig +short A zjsjgjyyzx.cn @dns10.hichina.com

所有结果都应为：

124.220.83.186

中国大陆服务器使用 HTTP-01 申请证书前，应确保域名备案已通过并已生效。若备案未完成或 DNS 线路未完全刷新，Let’s Encrypt 可能访问到运营商/平台拦截页，导致验证失败。

4.2 Nginx 与端口

docker inspect nginx --format 'status={{.State.Status}} ports={{json .HostConfig.PortBindings}}'
docker exec nginx nginx -t
ss -lntp | grep -E ':(80|443)([[:space:]]|$)'

预期：

Nginx 容器为 running
宿主机 80 和 443 都由 Docker 映射监听
nginx -t 通过

4.3 ACME 校验路径

HTTP-01 校验规则必须存在于 zhjzpt.conf 的 server 块内：

location ^~ /.well-known/acme-challenge/ {
    root /usr/share/nginx/html;
    try_files $uri =404;
    default_type text/plain;
}

验证校验路径：

mkdir -p /data/nginx/html/.well-known/acme-challenge
printf 'acme-check-ok\n' \
  > /data/nginx/html/.well-known/acme-challenge/verify-test

curl -i http://zjsjgjyyzx.cn/.well-known/acme-challenge/verify-test
rm -f /data/nginx/html/.well-known/acme-challenge/verify-test

必须收到 200 OK 和测试文本；校验文件不能被 SPA fallback 返回为首页 HTML。

5. 申请 SSL 证书

5.1 安装 Certbot

Ubuntu 22.04：

apt-get update -qq
apt-get install -y -qq certbot

检查：

certbot --version
systemctl status certbot.timer --no-pager

5.2 使用 HTTP-01 Webroot 签发

certbot certonly \
  --webroot \
  -w /data/nginx/html \
  -d zjsjgjyyzx.cn \
  --non-interactive \
  --agree-tos \
  -m '<运维联系邮箱>' \
  --keep-until-expiring

成功后检查：

openssl x509 \
  -in /etc/letsencrypt/live/zjsjgjyyzx.cn/fullchain.pem \
  -noout -subject -issuer -dates

将证书同步到 Nginx 挂载目录：

install -d -o root -g root -m 0755 /data/nginx/ssl/zjsjgjyyzx.cn
install -o root -g root -m 0644 \
  /etc/letsencrypt/live/zjsjgjyyzx.cn/fullchain.pem \
  /data/nginx/ssl/zjsjgjyyzx.cn/fullchain.pem
install -o root -g root -m 0600 \
  /etc/letsencrypt/live/zjsjgjyyzx.cn/privkey.pem \
  /data/nginx/ssl/zjsjgjyyzx.cn/privkey.pem

5.3 常见申请失败：CA 命中旧 IP 或拦截页

若 Certbot 输出中出现非本服务器 IP，或类似：

Invalid response from https://dnspod.qcloud.com/static/webblock.html

不要继续重复申请。先检查：

所有 DNS 线路是否统一为 124.220.83.186
域名备案是否已生效
80 端口是否可从公网访问
/.well-known/acme-challenge/ 是否返回实际验证文件
是否存在旧 A 记录、CNAME、线路分流或平台拦截

6. Nginx 配置

6.1 HTTP 80 配置

文件：

/data/nginx/conf/conf.d/zhjzpt.conf

HTTP 站点应继续：

server {
    listen 80;
    server_name zjsjgjyyzx.cn 124.220.83.186 _;
    # 保留现有静态页面与代理规则
}

不要加入以下跳转规则，否则不再满足 HTTP、HTTPS 都直接可访问的要求：

return 301 https://$host$request_uri;

6.2 HTTPS 443 配置

文件：

/data/nginx/conf/conf.d/zhjzpt-ssl.conf

HTTPS 配置应与 HTTP 站点保持功能等价，至少包含：

静态站点根目录：/usr/share/nginx/html/admin-ui
/kkfileview/ 代理
/dp/ 静态目录
/.well-known/acme-challenge/ 规则
/admin-api/ 代理
/app-api/ 代理
根路径 SPA fallback

核心 TLS 配置：

server {
    listen 443 ssl;
    server_name zjsjgjyyzx.cn;

    root /usr/share/nginx/html/admin-ui;
    index index.html;
    charset utf-8;

    ssl_certificate /etc/nginx/ssl/zjsjgjyyzx.cn/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/zjsjgjyyzx.cn/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 以下保持与 HTTP 站点相同的静态和代理 location
}

配置修改前先备份：

TS=$(date +%Y%m%d%H%M%S)
cp -p /data/nginx/conf/conf.d/zhjzpt.conf \
  "/data/nginx/conf/conf.d/zhjzpt.conf.bak-$TS-before-change"

[ ! -f /data/nginx/conf/conf.d/zhjzpt-ssl.conf ] || \
  cp -p /data/nginx/conf/conf.d/zhjzpt-ssl.conf \
  "/data/nginx/conf/conf.d/zhjzpt-ssl.conf.bak-$TS"

检查并 reload：

docker exec nginx nginx -t
docker exec nginx nginx -s reload

nginx -t 失败时不得 reload。应先恢复备份，重新检查通过后再 reload。

7. Certbot 自动续期

7.1 Deploy Hook 内容

创建：

/etc/letsencrypt/renewal-hooks/deploy/zjsjgjyyzx.cn-nginx.sh

内容：

#!/bin/sh
set -eu

DOMAIN="zjsjgjyyzx.cn"
LIVE="/etc/letsencrypt/live/${DOMAIN}"
TARGET="/data/nginx/ssl/${DOMAIN}"

install -d -o root -g root -m 0755 "$TARGET"
install -o root -g root -m 0644 "$LIVE/fullchain.pem" "$TARGET/fullchain.pem"
install -o root -g root -m 0600 "$LIVE/privkey.pem" "$TARGET/privkey.pem"

docker exec nginx nginx -t
docker exec nginx nginx -s reload

设置权限：

chmod 700 /etc/letsencrypt/renewal-hooks/deploy/zjsjgjyyzx.cn-nginx.sh

7.2 测试续期

certbot renew --dry-run
systemctl is-enabled certbot.timer
systemctl is-active certbot.timer

预期：

certbot renew --dry-run：模拟续期成功
enabled
active

8. 域名根目录校验文件

主站根目录是：

/data/nginx/html/admin-ui/

发布第三方验证文件时，保持原始文件名和内容。例如文件名为 example.txt：

install -o root -g root -m 0644 /tmp/example.txt \
  /data/nginx/html/admin-ui/example.txt

验证：

curl -i http://zjsjgjyyzx.cn/example.txt
curl -i https://zjsjgjyyzx.cn/example.txt

两个地址都应返回：

HTTP/1.1 200 OK

当前已发布的校验文件：

/data/nginx/html/admin-ui/f7TyKy8B8f.txt

对应访问地址：

http://zjsjgjyyzx.cn/f7TyKy8B8f.txt
https://zjsjgjyyzx.cn/f7TyKy8B8f.txt

9. 部署后验证

9.1 HTTP 与 HTTPS 首页

curl -I --max-time 30 http://zjsjgjyyzx.cn/
curl -I --max-time 30 https://zjsjgjyyzx.cn/

两者都应返回：

HTTP/1.1 200 OK

HTTP 不应返回 301/302 到 HTTPS。

9.2 TLS 证书

printf '' | openssl s_client \
  -connect zjsjgjyyzx.cn:443 \
  -servername zjsjgjyyzx.cn 2>/dev/null |
  openssl x509 -noout -subject -issuer -dates

预期主体：

subject=CN=zjsjgjyyzx.cn

9.3 HTTPS API

curl -sS -o /dev/null -w '%{http_code} %{content_type}\n' \
  --max-time 30 \
  https://zjsjgjyyzx.cn/app-api/system/menu/list

预期：

200 application/json;charset=UTF-8

9.4 Nginx 与续期

docker exec nginx nginx -t
certbot certificates
certbot renew --dry-run

10. 回滚

10.1 回滚 HTTPS 配置

如果 HTTPS 新配置导致 nginx -t 失败或业务异常：

set -e
CFGDIR=/data/nginx/conf/conf.d
BACKUP="$CFGDIR/zhjzpt-ssl.conf.bak-YYYYMMDDHHMMSS"

test -f "$BACKUP"
cp -p "$BACKUP" "$CFGDIR/zhjzpt-ssl.conf"
docker exec nginx nginx -t
docker exec nginx nginx -s reload

如果需要临时停用 HTTPS server：

set -e
mv /data/nginx/conf/conf.d/zhjzpt-ssl.conf \
  /data/nginx/conf/conf.d/zhjzpt-ssl.conf.disabled

docker exec nginx nginx -t
docker exec nginx nginx -s reload

这不会影响现有 HTTP 80 站点。

10.2 回滚 HTTP 配置

只在误改 zhjzpt.conf 时恢复：

set -e
CFGDIR=/data/nginx/conf/conf.d
BACKUP="$CFGDIR/zhjzpt.conf.bak-YYYYMMDDHHMMSS-before-change"

test -f "$BACKUP"
cp -p "$BACKUP" "$CFGDIR/zhjzpt.conf"
docker exec nginx nginx -t
docker exec nginx nginx -s reload

不要删除 /data/nginx/html/admin-ui/ 整个目录，以免影响后台前端和根目录校验文件。

11. 2026-09-07 实施记录

域名备案生效后，权威 DNS 和公共 DNS 均解析到 124.220.83.186。
使用 Certbot HTTP-01 Webroot 模式成功签发 zjsjgjyyzx.cn 证书。
证书签发机构：Let’s Encrypt YR2。
该证书有效至 2026-12-06 01:29:53 GMT。
新增 zhjzpt-ssl.conf，监听 443 ssl。
保留 zhjzpt.conf 的 80 HTTP 站点，不执行 HTTP 到 HTTPS 跳转。
HTTP 首页、HTTPS 首页和 HTTPS /app-api/system/menu/list 均验证返回 200。
Certbot renew --dry-run 成功。
certbot.timer 处于 enabled 和 active 状态。
发布根目录校验文件 f7TyKy8B8f.txt，HTTP 和 HTTPS 均返回 200。

12 KiB Raw Blame History Unescape Escape