lyf
337446f33c
Some checks failed
CI / verify (push) Has been cancelled
- 详情页路由入参统一为 stopId，废弃 targetType/targetId - ExplainDetailEntryRequest 与 GlobalAudioSource 移除 targetType/targetId 字段 - 播放器源匹配仅按 stopId 判定，移除 targetType 兜底 - 删除 explainDetailTarget 死代码 - 清理 guideStopInfoAdapter 中 stop/info、play-info、text-info 旧契约类型与转换函数 - 补充测试服务器 Nginx SSL 部署手册 - 同步更新单测与 e2e 用例 Made-with: Proma
535 lines
12 KiB
Markdown
535 lines
12 KiB
Markdown
# 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`，其部署手册见：
|
||
|
||
```text
|
||
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` |
|
||
|
||
请求链路：
|
||
|
||
```text
|
||
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 配置：
|
||
|
||
```text
|
||
/data/nginx/conf/conf.d/zhjzpt.conf
|
||
```
|
||
|
||
主站 HTTPS 配置：
|
||
|
||
```text
|
||
/data/nginx/conf/conf.d/zhjzpt-ssl.conf
|
||
```
|
||
|
||
### 3.2 证书
|
||
|
||
Certbot 管理的原始证书：
|
||
|
||
```text
|
||
/etc/letsencrypt/live/zjsjgjyyzx.cn/fullchain.pem
|
||
/etc/letsencrypt/live/zjsjgjyyzx.cn/privkey.pem
|
||
```
|
||
|
||
Nginx 容器读取的同步副本：
|
||
|
||
```text
|
||
/data/nginx/ssl/zjsjgjyyzx.cn/fullchain.pem
|
||
/data/nginx/ssl/zjsjgjyyzx.cn/privkey.pem
|
||
```
|
||
|
||
权限要求：
|
||
|
||
```text
|
||
fullchain.pem: 0644
|
||
privkey.pem: 0600
|
||
```
|
||
|
||
### 3.3 自动续期 Hook
|
||
|
||
```text
|
||
/etc/letsencrypt/renewal-hooks/deploy/zjsjgjyyzx.cn-nginx.sh
|
||
```
|
||
|
||
该 Hook 在证书续期成功后执行以下操作：
|
||
|
||
1. 将证书复制到 `/data/nginx/ssl/zjsjgjyyzx.cn/`。
|
||
2. 设置证书与私钥的安全权限。
|
||
3. 执行 `docker exec nginx nginx -t`。
|
||
4. 执行 `docker exec nginx nginx -s reload`。
|
||
|
||
## 4. 部署前检查
|
||
|
||
### 4.1 DNS 与备案
|
||
|
||
域名 A 记录必须统一指向：
|
||
|
||
```text
|
||
zjsjgjyyzx.cn -> 124.220.83.186
|
||
```
|
||
|
||
至少使用多个公共 DNS 核对：
|
||
|
||
```bash
|
||
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，可检查权威记录：
|
||
|
||
```bash
|
||
dig +short A zjsjgjyyzx.cn @dns9.hichina.com
|
||
dig +short A zjsjgjyyzx.cn @dns10.hichina.com
|
||
```
|
||
|
||
所有结果都应为：
|
||
|
||
```text
|
||
124.220.83.186
|
||
```
|
||
|
||
中国大陆服务器使用 HTTP-01 申请证书前，应确保域名备案已通过并已生效。若备案未完成或 DNS 线路未完全刷新，Let’s Encrypt 可能访问到运营商/平台拦截页，导致验证失败。
|
||
|
||
### 4.2 Nginx 与端口
|
||
|
||
```bash
|
||
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` 块内：
|
||
|
||
```nginx
|
||
location ^~ /.well-known/acme-challenge/ {
|
||
root /usr/share/nginx/html;
|
||
try_files $uri =404;
|
||
default_type text/plain;
|
||
}
|
||
```
|
||
|
||
验证校验路径：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
apt-get update -qq
|
||
apt-get install -y -qq certbot
|
||
```
|
||
|
||
检查：
|
||
|
||
```bash
|
||
certbot --version
|
||
systemctl status certbot.timer --no-pager
|
||
```
|
||
|
||
### 5.2 使用 HTTP-01 Webroot 签发
|
||
|
||
```bash
|
||
certbot certonly \
|
||
--webroot \
|
||
-w /data/nginx/html \
|
||
-d zjsjgjyyzx.cn \
|
||
--non-interactive \
|
||
--agree-tos \
|
||
-m '<运维联系邮箱>' \
|
||
--keep-until-expiring
|
||
```
|
||
|
||
成功后检查：
|
||
|
||
```bash
|
||
openssl x509 \
|
||
-in /etc/letsencrypt/live/zjsjgjyyzx.cn/fullchain.pem \
|
||
-noout -subject -issuer -dates
|
||
```
|
||
|
||
将证书同步到 Nginx 挂载目录：
|
||
|
||
```bash
|
||
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，或类似：
|
||
|
||
```text
|
||
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 配置
|
||
|
||
文件：
|
||
|
||
```text
|
||
/data/nginx/conf/conf.d/zhjzpt.conf
|
||
```
|
||
|
||
HTTP 站点应继续：
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name zjsjgjyyzx.cn 124.220.83.186 _;
|
||
# 保留现有静态页面与代理规则
|
||
}
|
||
```
|
||
|
||
不要加入以下跳转规则，否则不再满足 HTTP、HTTPS 都直接可访问的要求：
|
||
|
||
```nginx
|
||
return 301 https://$host$request_uri;
|
||
```
|
||
|
||
### 6.2 HTTPS 443 配置
|
||
|
||
文件：
|
||
|
||
```text
|
||
/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 配置：
|
||
|
||
```nginx
|
||
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
|
||
}
|
||
```
|
||
|
||
配置修改前先备份：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
docker exec nginx nginx -t
|
||
docker exec nginx nginx -s reload
|
||
```
|
||
|
||
`nginx -t` 失败时不得 reload。应先恢复备份，重新检查通过后再 reload。
|
||
|
||
## 7. Certbot 自动续期
|
||
|
||
### 7.1 Deploy Hook 内容
|
||
|
||
创建：
|
||
|
||
```text
|
||
/etc/letsencrypt/renewal-hooks/deploy/zjsjgjyyzx.cn-nginx.sh
|
||
```
|
||
|
||
内容：
|
||
|
||
```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
|
||
```
|
||
|
||
设置权限：
|
||
|
||
```bash
|
||
chmod 700 /etc/letsencrypt/renewal-hooks/deploy/zjsjgjyyzx.cn-nginx.sh
|
||
```
|
||
|
||
### 7.2 测试续期
|
||
|
||
```bash
|
||
certbot renew --dry-run
|
||
systemctl is-enabled certbot.timer
|
||
systemctl is-active certbot.timer
|
||
```
|
||
|
||
预期：
|
||
|
||
```text
|
||
certbot renew --dry-run：模拟续期成功
|
||
enabled
|
||
active
|
||
```
|
||
|
||
## 8. 域名根目录校验文件
|
||
|
||
主站根目录是：
|
||
|
||
```text
|
||
/data/nginx/html/admin-ui/
|
||
```
|
||
|
||
发布第三方验证文件时，保持原始文件名和内容。例如文件名为 `example.txt`：
|
||
|
||
```bash
|
||
install -o root -g root -m 0644 /tmp/example.txt \
|
||
/data/nginx/html/admin-ui/example.txt
|
||
```
|
||
|
||
验证：
|
||
|
||
```bash
|
||
curl -i http://zjsjgjyyzx.cn/example.txt
|
||
curl -i https://zjsjgjyyzx.cn/example.txt
|
||
```
|
||
|
||
两个地址都应返回：
|
||
|
||
```text
|
||
HTTP/1.1 200 OK
|
||
```
|
||
|
||
当前已发布的校验文件：
|
||
|
||
```text
|
||
/data/nginx/html/admin-ui/f7TyKy8B8f.txt
|
||
```
|
||
|
||
对应访问地址：
|
||
|
||
```text
|
||
http://zjsjgjyyzx.cn/f7TyKy8B8f.txt
|
||
https://zjsjgjyyzx.cn/f7TyKy8B8f.txt
|
||
```
|
||
|
||
## 9. 部署后验证
|
||
|
||
### 9.1 HTTP 与 HTTPS 首页
|
||
|
||
```bash
|
||
curl -I --max-time 30 http://zjsjgjyyzx.cn/
|
||
curl -I --max-time 30 https://zjsjgjyyzx.cn/
|
||
```
|
||
|
||
两者都应返回：
|
||
|
||
```text
|
||
HTTP/1.1 200 OK
|
||
```
|
||
|
||
HTTP 不应返回 `301/302` 到 HTTPS。
|
||
|
||
### 9.2 TLS 证书
|
||
|
||
```bash
|
||
printf '' | openssl s_client \
|
||
-connect zjsjgjyyzx.cn:443 \
|
||
-servername zjsjgjyyzx.cn 2>/dev/null |
|
||
openssl x509 -noout -subject -issuer -dates
|
||
```
|
||
|
||
预期主体：
|
||
|
||
```text
|
||
subject=CN=zjsjgjyyzx.cn
|
||
```
|
||
|
||
### 9.3 HTTPS API
|
||
|
||
```bash
|
||
curl -sS -o /dev/null -w '%{http_code} %{content_type}\n' \
|
||
--max-time 30 \
|
||
https://zjsjgjyyzx.cn/app-api/system/menu/list
|
||
```
|
||
|
||
预期：
|
||
|
||
```text
|
||
200 application/json;charset=UTF-8
|
||
```
|
||
|
||
### 9.4 Nginx 与续期
|
||
|
||
```bash
|
||
docker exec nginx nginx -t
|
||
certbot certificates
|
||
certbot renew --dry-run
|
||
```
|
||
|
||
## 10. 回滚
|
||
|
||
### 10.1 回滚 HTTPS 配置
|
||
|
||
如果 HTTPS 新配置导致 `nginx -t` 失败或业务异常：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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` 时恢复：
|
||
|
||
```bash
|
||
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`。
|