重置项目

2026-07-04 15:59:20 +08:00
parent 374e587f2d
commit 648a8b7f1c
224 changed files with 19700 additions and 9547 deletions
@@ -0,0 +1,99 @@
+# 公网部署:如何设置访问密码
+
+面板部署在公网服务器时,首次设置访问密码有限制 —— **必须从本机或内网访问**,以防公网上陌生人抢先设置密码锁死你的面板。
+
+如果你在公网浏览器直接打开页面,会看到提示:
+
+> 首次设置密码仅允许本机或内网访问,请通过 SSH/本地浏览器操作
+
+有两种方式解决,任选其一。
+
+---
+
+## 方式一:环境变量预置密码(最简单,推荐)
+
+在 `.env` 文件(或 Docker / 系统环境变量)里设置 `AUTH_PASSWORD`:
+
+```bash
+# 编辑服务器上的 .env (通常在项目根目录或 backend/ 下)
+AUTH_PASSWORD=你的密码
+```
+
+然后重启服务。启动时会自动:
+1. 读取 `AUTH_PASSWORD`
+2. 用 PBKDF2 哈希后写入 `auth.json`(`chmod 600`,只存哈希不存明文)
+3. **之后这个环境变量就不再被读取** —— 是一次性的初始化
+
+设完后即可用公网地址 + 这个密码正常登录。后续改密码请用页面 UI(`设置 → 修改密码`),不受环境变量影响。
+
+### 注意事项
+
+- **密码至少 6 位**,否则会被跳过并记一条 warning 日志
+- **仅在未设过密码时生效**。已设过密码后,改这里不会覆盖(避免重启时重置你在 UI 改的密码)
+- `.env` 文件权限保持 `600`,**不要提交到 Git**
+- 明文密码只存在于 `.env` / 环境变量中,落盘的是哈希,安全性等同 `auth.json`
+
+### 重置密码(忘密码时)
+
+如果忘了密码想重置:删除或清空 `data/user_data/auth.json`,重启服务,会回到"未设密码"状态,此时 `AUTH_PASSWORD` 会重新生效。
+
+```bash
+# 停服后执行, 清空后重启
+rm data/user_data/auth.json
+```
+
+---
+
+## 方式二:SSH 端口转发
+
+不用改配置,在你**自己电脑**的终端执行(不是服务器上):
+
+```bash
+ssh -L 3018:127.0.0.1:3018 用户名@服务器IP
+```
+
+例如服务器是 `123.45.67.89`、用户名 `root`、面板端口 `3018`:
+
+```bash
+ssh -L 3018:127.0.0.1:3018 root@123.45.67.89
+```
+
+保持这个 SSH 连接**不要关**,然后在**自己电脑的浏览器**打开:
+
+```
+http://127.0.0.1:3018
+```
+
+此时后端看到的客户端 IP 是 `127.0.0.1`(本机),能通过校验,正常显示设置密码界面。
+
+**设完密码后**,SSH 连接可以断开 —— 密码已存进服务器,之后直接用公网地址 + 刚设的密码访问即可。
+
+### 端口说明
+
+上面的 `3018` 是默认端口。如果你用 `PORT` 环境变量改过端口(比如 `PORT=8080`),两处都要替换:
+
+```bash
+ssh -L 8080:127.0.0.1:8080 root@123.45.67.89
+```
+
+---
+
+## 原理说明
+
+- **为什么限制本机/内网?** 面板部署到公网后,任何人都能访问 URL。如果不限制,攻击者可以在你之前打开页面、设置一个密码,把你的面板锁死。
+- **本机/内网如何判断?** 后端检查客户端 IP 是否属于 `127.0.0.1 / ::1 / 10.x / 192.168.x / 172.16-31.x`。
+- **SSH 转发为什么有效?** `-L` 把本机端口通过 SSH 隧道转发到服务器的 `127.0.0.1`,等同于在服务器本地访问,客户端 IP 变成 `127.0.0.1`,通过校验。
+- **反向代理注意:** 若面板在 Nginx 等反代之后,需正确配置 `X-Forwarded-For` 头,后端据此取真实客户端 IP。
+
+---
+
+## 两种方式怎么选
+
+| | 环境变量 | SSH 转发 |
+|---|---|---|
+| 操作 | 改一行配置 + 重启 | 一条 ssh 命令 |
+| 需要改配置 | 是 | 否 |
+| 适合 | Docker / 自动化部署 / 不熟 SSH | 临时设密码 / 能 SSH 到服务器 |
+| 后续改密码 | UI(`设置 → 修改密码`) | 同左 |
+
+推荐**方式一(环境变量)**,一次配置即可,Docker 部署尤其方便。