From eb478a6e13f070b77dd8d6564a1187020d04e0d5 Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Sat, 24 Oct 2026 14:22:22 +0800
Subject: [PATCH] docs: explain creating the first 1Panel proxy site

---
 server/updates/README.md                      | 69 +++++++++++++++++--
 .../updates/openresty-safeline.conf.example   |  3 +-
 2 files changed, 66 insertions(+), 6 deletions(-)

diff --git a/server/updates/README.md b/server/updates/README.md
index d00fcd3..84ed001 100644
--- a/server/updates/README.md
+++ b/server/updates/README.md
@@ -4,7 +4,7 @@
 
 ## Ubuntu、1Panel、雷池部署步骤
 
-已知环境：雷池80/443 → host网络的OpenResty10080 → 原反馈容器18080。新增更新容器仅监听 `127.0.0.1:18081`；反馈服务、SMTP、域名证书、原路由均不需要修改。本工程没有访问服务器或执行部署。
+按已说明的环境配置：雷池占用80/443，OpenResty使用host网络、HTTP10080/HTTPS12443。即使1Panel中尚无网站，也可以按下方第4步新建转发站点。新增更新容器仅监听 `127.0.0.1:18081`，反馈容器继续使用18080；新站点分别转发这两个服务，不需要修改反馈代码、SMTP或雷池证书。本工程没有访问服务器或执行部署。
 
 ### 1. 上传服务文件
 
@@ -59,13 +59,70 @@ curl --fail --max-time 10 http://127.0.0.1:18081/v1/updates/android
 
 `.env`、Compose项目名`tpschedule-updates`及`update-data`数据卷要长期保留；正常重建不会清空版本。不要执行带 `-v` 的删除数据卷命令。服务配置错误时检查 `docker compose logs --tail 30 updates`，分享错误前不要附带.env或秘密值。
 
-### 4. 配置现有OpenResty站点
+### 4. 创建或配置OpenResty转发站点
 
-1Panel“网站”→`app.glowtps.cn`→配置文件，在现有 `server { … }` 内添加 `openresty-safeline.conf.example` 中的三个 `location`。不要把三个location放到已有location内部，不要另建相同域名的server；若已有相同路径请合并替换，不重复定义。
+没有在1Panel建过网站也可以，创建一个反向代理站点即可，不需要上传网页、安装PHP或创建数据库。
 
-这三个路径转发至 `http://127.0.0.1:18081`，原 `/v1/feedback` 仍转发至18080。验证配置并重载OpenResty。无需改变10080/12443监听、雷池回源地址和TLS证书；内部10080站点仍不强制跳转HTTPS。
+**4.1 如果尚无站点**
 
-雷池保持 `app.glowtps.cn → 127.0.0.1:10080`。如果雷池启用了必须由浏览器完成的人机验证，仅对APP查询路径 `/v1/updates/android` 关闭交互挑战；保留网站其他保护。此API是公开、只读的版本信息，不能要求管理员登录或返回HTML挑战页面。后台 `/update` 保持正常防护，登录和发布使用POST，不能缓存这些路径。
+确认1Panel已安装OpenResty。若没有，在应用商店安装，HTTP端口使用10080、HTTPS端口使用12443，继续使用host网络；80/443留给雷池。若已经安装且是上述配置，不需要重装。
+
+1Panel“网站”→“创建网站”→“反向代理”，填写：
+
+| 项目 | 内容 |
+| --- | --- |
+| 主域名 | `app.glowtps.cn:10080`；如果界面有单独端口栏，域名填`app.glowtps.cn`、端口填`10080` |
+| 代理地址 | `http://127.0.0.1:18081` |
+| 代号／备注 | `tpschedule-app`／TPSchedule更新与反馈 |
+| 启用HTTPS | 不勾选；外部证书由雷池提供 |
+| 强制HTTPS跳转 | 关闭，避免雷池HTTP回源循环跳转 |
+
+创建后，在站点配置中确认`listen 10080;`和`server_name app.glowtps.cn;`。`server_name`不带`:10080`。具体菜单名称可能因1Panel版本略有不同。
+
+**4.2 配置路径和保留反馈接口**
+
+打开1Panel“网站”→`app.glowtps.cn`→配置文件，在`server { … }`内添加`openresty-safeline.conf.example`中的三个location。如果已有站点则直接从这里开始。新建的反向代理站点通常已有`location /`，保留它；新增的精确路径规则与它并存。不要把location嵌套在另一个location里，不要重复定义同名路径。
+
+如果当前反馈服务已经运行在18080，还要加入下面的精确路由，否则把整个域名改为回源新服务会使原反馈接口失效：
+
+```nginx
+location = /v1/feedback {
+    client_max_body_size 24m;
+    client_body_timeout 60s;
+    proxy_request_buffering off;
+    proxy_buffering off;
+    proxy_http_version 1.1;
+    proxy_pass http://127.0.0.1:18080;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto https;
+    proxy_set_header Connection "";
+    proxy_connect_timeout 5s;
+    proxy_send_timeout 180s;
+    proxy_read_timeout 180s;
+    proxy_next_upstream off;
+    access_log off;
+}
+```
+
+反馈服务还没部署时可以暂不添加这一条，更新后台不依赖反馈服务。若新站点需要还原真实客户端IP，在server层配置`set_real_ip_from 127.0.0.1;`、`set_real_ip_from ::1;`、`real_ip_header X-Forwarded-For;`和`real_ip_recursive on;`，已有相同设置时不重复添加。它们信任的是同机雷池回源，不是任意公网来源。
+
+验证配置并重载OpenResty。先在服务器终端检查内部转发，不要立即改雷池现有上游：
+
+```sh
+curl --fail --max-time 10 -H 'Host: app.glowtps.cn' http://127.0.0.1:10080/v1/updates/android
+```
+
+应返回版本JSON（首次latest为null）。若返回404、502或其他站点页面，先检查站点监听端口、Host和18081容器，不需要关闭或修改雷池其他站点。
+
+**4.3 配置雷池回源**
+
+内部检查通过后，在雷池编辑`app.glowtps.cn`这一个站点：域名仍为`app.glowtps.cn`，公网HTTPS端口443和证书保持，上游协议HTTP、地址`127.0.0.1:10080`；若上游栏要求完整URL，填`http://127.0.0.1:10080`。如果原先直接回源18080，此时才切换到10080；其他域名和雷池管理设置不改。
+
+最终链路是：浏览器/APP→雷池443→OpenResty10080→更新服务18081或反馈服务18080。无需开放18080/18081公网端口，也不需要为1Panel再申请一份网站证书。
+
+如果雷池启用了必须由浏览器完成的人机验证，仅对APP查询路径`/v1/updates/android`关闭交互挑战；保留网站其他保护。此API是公开、只读的版本信息，不能要求管理员登录或返回HTML挑战页面。后台`/update`保持正常防护，登录和发布使用POST，不能缓存这些路径。
 
 浏览器打开 `https://app.glowtps.cn/update`，应看到蓝色登录页面。后台使用Secure Cookie，必须通过外部HTTPS访问，直接用服务器IP或HTTP测试登录会失败。随后访问公开JSON接口核对转发。
 
@@ -81,6 +138,8 @@ curl --fail --max-time 10 http://127.0.0.1:18081/v1/updates/android
 
 更新提示是启动/手动联网检查，并非APP关闭后的系统通知，也不静默安装。用户点击立即更新后通过浏览器下载并按Android提示安装，APP不申请“安装未知应用”权限。需要允许浏览器安装来源时由Android和浏览器处理。
 
+创建反向代理网站及主域名/端口设置依据1Panel官方文档：https://docs.fit2cloud.com/1panel/user_manual/websites/website-create/ 。上文端口与转发规则按本工程和用户已说明的雷池同机环境制定，尚未在实际服务器执行。
+
 ### 6. 第一次如何让同学接入
 
 0.7.5及之前的APP没有检查更新代码，服务器无法给它们凭空补上。第一次仍需手动分发、覆盖安装0.7.6；之后这些用户才能收到你在后台发布的后续版本。**不要卸载旧版**，原包名、签名一致时覆盖安装保留本机课表。
diff --git a/server/updates/openresty-safeline.conf.example b/server/updates/openresty-safeline.conf.example
index d098767..4ed016f 100644
--- a/server/updates/openresty-safeline.conf.example
+++ b/server/updates/openresty-safeline.conf.example
@@ -1,4 +1,5 @@
-# Add inside the EXISTING app.glowtps.cn HTTP server listening on 10080.
+# Add inside the app.glowtps.cn HTTP server listening on 10080.
+# If no site exists, create a reverse-proxy site first; see README.md section 4.
 # SafeLine continues to terminate public HTTPS on 443. No new public port.
 # Reuse the site's existing real-IP configuration; do not duplicate it here.