dekun/LocalNav
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add system settings, one-click deploy, and simplify embed UI.

Browse Source 
Remove Gate scout auto-seeding and the manual hub login button while keeping Gate login and instance SSO. Add password change and database backup/restore, plus deploy scripts with env auto-generation.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-07-12 11:44:12 +08:00
parent f7ce6f1058
commit 3149770887
15 changed files with 635 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files
部署与使用说明.md
+101 -70
View File
@@ -26,6 +26,7 @@
| 导航首页 | 左右分栏；左侧分组与服务；右侧 iframe 内嵌打开目标页。 |
| 分组管理 | 新增 / 编辑 / 删除分组；支持排序字段（数字越小越靠前）。 |
| 服务管理 | 新增 / 编辑 / 删除服务；字段：名称、内网主机、端口、路径、所属分组、排序。 |
| 系统设置 | 修改登录密码；数据库一键备份与恢复。 |
| 数据库 | SQLite，默认文件名为 `nav_local.db`（与运行当前工作目录有关）。 |
| 网络监听 | 默认绑定 `0.0.0.0`，便于同局域网手机、电脑访问。 |
@@ -52,6 +53,11 @@
├── .env.example # 环境变量模板（复制为 .env 后修改）
├── .env # 本地配置（自建，勿提交 Git）
├── ecosystem.config.cjs # PM2 守护进程配置
├── scripts/
│ ├── deploy.py # 一键部署（环境检测、生成 .env）
│ ├── deploy.sh # Linux/macOS 封装
│ ├── deploy.ps1 # Windows 封装
│ └── cleanup_gate_scout.py # 可选：清理旧「Gate 扫单」分组
├── nav_local.db # SQLite 数据库（首次成功运行后生成，勿手误提交到公开仓库）
├── static/
│ └── style.css # 样式
@@ -63,11 +69,50 @@
├── admin_group_form.html
├── admin_services.html
└── admin_service_form.html
└── admin_settings.html
```
---
## 五、环境变量与 `.env` 文件
## 五、一键部署（推荐）
项目提供跨平台部署脚本，自动完成环境检测、虚拟环境创建、依赖安装、`.env` 生成与 `NAV_SECRET_KEY` 写入。
```bash
# Linux / macOS
bash scripts/deploy.sh
# Windows PowerShell
.\scripts\deploy.ps1
# 或直接
python scripts/deploy.py
```
**脚本行为：**
| 步骤 | 说明 |
|------|------|
| 环境检测 | Python 3.10+、pip；可选检测 git、pm2 |
| 生成 `.env` | 从 `.env.example` 复制（若不存在） |
| `NAV_SECRET_KEY` | 若为空则自动生成 64 位 hex |
| 默认账号 | `NAV_ADMIN_USERNAME=admin`、`NAV_ADMIN_PASSWORD=admin123` |
| 中控自动登录 | 默认 `NAV_HUB_AUTO_LOGIN=1` |
| 内网 Cookie | 默认 `NAV_COOKIES_INSECURE_HTTP=1`（便于 `http://IP:端口` 访问） |
**注意：** 脚本不会覆盖 `.env` 中已有的 `NAV_SECRET_KEY` 等配置。生产环境部署后请尽快登录并在「系统设置」中修改密码。
部署完成后启动：
```bash
.venv/bin/python app.py # Linux
# 或
pm2 start ecosystem.config.cjs # 需已安装 PM2
```
---
## 六、环境变量与 `.env` 文件
程序启动时会从 **与 `app.py` 同目录** 的 `.env` 文件加载变量（依赖 `python-dotenv`）。**若 `.env` 不存在则跳过，不影响启动。**
@@ -106,7 +151,7 @@ $env:NAV_SECRET_KEY = -join ((48..57) + (65..90) + (97..122) | Get-Random -Count
---
## 六、安装与运行（通用）
## 七、安装与运行（通用）
### 6.1 获取代码
@@ -174,43 +219,42 @@ http://<本机局域网IP>:5070
---
## 七、首次登录与默认账号
## 八、首次登录与默认账号
1. 第一次成功启动且数据库中 **没有任何用户** 时，程序会自动创建：
- 用户：**`admin`**
- 密码：**`admin123`**
- 一个名为 **「默认分组」** 的空分组。
2. 控制台会打印一行提示（内容大意：默认账号仅内网使用，请尽快修改）。
3. 一键部署脚本 `scripts/deploy.py` 会写入相同的默认账号；若 `.env` 中已有 `NAV_ADMIN_USERNAME` / `NAV_ADMIN_PASSWORD` 则以其为准。
**安全建议（强烈）**：
- 首次登录后，尽快通过可靠方式修改密码。当前版本未内置「改密页」，可自行选用其一：
- 使用 [DB Browser for SQLite](https://sqlitebrowser.org/) 等工具打开 `nav_local.db`，删除 `users` 表中对应用户后，临时改代码跑一次初始化（不推荐反复操作）；
- 或自行增加「修改密码」路由（二次开发）。
- 首次登录后，请进入顶部 **「系统设置」** 修改密码。
- **不要将**带默认口令的数据库文件提交到公开 Git 仓库。
- 本应用设计为 **内网聚合入口**；若需外网访问，请按 **9.8** 配置 HTTPS 与反向代理，勿将 `5070` 端口裸奔到公网。
- 本应用设计为 **内网聚合入口**；若需外网访问，请按 **10.8** 配置 HTTPS 与反向代理，勿将 `5070` 端口裸奔到公网。
---
## 八、使用说明（操作层面）
## 九、使用说明（操作层面）
### 8.1 登录
### 9.1 登录
访问站点根路径，未登录会跳转至 **`/login`**，输入用户名与密码即可。
### 8.2 导航首页（`/`）
### 9.2 导航首页（`/`）
- **左侧**：按分组展示服务名称；点击后在 **右侧 iframe** 打开对应地址。
- **顶部**：可进入「分组管理」「服务管理」或退出登录。
- **内嵌页工具栏**：「刷新」为普通刷新（追加时间戳参数）；「强制刷新」等同 **Ctrl+F5**，先清空 iframe 再带随机参数重新加载，尽量跳过浏览器缓存（跨域 iframe 时效果取决于目标站点策略）。
- **顶部**：可进入「分组管理」「服务管理」「系统设置」或退出登录。
- **内嵌页工具栏**：「Gate 登录」「实例免密」「刷新」「强制刷新」「新标签页」。中控嵌入须配置 `NAV_HUB_AUTO_LOGIN=1` 自动代登录（无手动「中控登录」按钮）。
### 8.3 分组管理（`/admin/groups`）
### 9.3 分组管理（`/admin/groups`）
- **新建 / 编辑**：填写分组名称、排序。
- **删除**：会 **同时删除** 该分组下的 **所有服务**（级联删除），请谨慎操作。
- 列表中可从某分组快捷 **「在此分组添加服务」**。
### 8.4 服务管理（`/admin/services`）
### 9.4 服务管理（`/admin/services`）
- 字段含义简要说明：
- **服务名称**：左侧显示名称。
@@ -232,11 +276,17 @@ http://<本机局域网IP>:5070
生成地址：`https://panel.example.com:443/`
### 8.5 关于 iframe 打不开的说明
### 9.5 系统设置（`/admin/settings`）
- **修改密码**：输入当前密码与新密码（至少 6 位），保存后立即生效。
- **一键备份**：下载当前 `nav_local.db` 文件（文件名带时间戳）。
- **一键恢复**：上传 `.db` 备份文件覆盖当前库；恢复前会自动在同目录生成 `nav_local.db.bak.时间戳`。**恢复后请重启 LocalNav 服务。**
### 9.6 关于 iframe 打不开的说明
部分网站（尤其银行、部分管理面板）通过 **`X-Frame-Options`** 或 **`Content-Security-Policy`** 禁止被嵌入 iframe，此时右侧区域可能为空白或浏览器控制台报错。这属于 **目标站点安全策略**，与本导航站实现无关。若必须统一入口，只能由目标服务侧放开嵌入策略，或改为新窗口打开（需改代码，非当前默认行为）。
### 8.6 云端「复盘中控」iframe 嵌入（LocalNav + manual_trading_hub）
### 9.7 云端「复盘中控」iframe 嵌入（LocalNav + manual_trading_hub）
本地导航（如 `http://192.168.x.x:5070`）嵌入 **云端中控**（`https://你的域名:5100`）时，浏览器会把中控 Cookie 视为**跨站第三方**，直接在 iframe 里登录常会「成功但进不去」。
@@ -249,8 +299,7 @@ http://<本机局域网IP>:5070
NAV_HUB_PASSWORD=你的中控密码
NAV_HUB_AUTO_LOGIN=1
```
3. 重启 LocalNav。打开中控时会由**本地服务端**代登录，iframe 再打开 `/embed-auth?token=...` 写入会话。
4. 也可在内嵌工具栏点 **「中控登录」** 手动触发。
3. 重启 LocalNav。打开中控时会由**本地服务端**自动代登录（`NAV_HUB_AUTO_LOGIN=1`），iframe 再打开 `/embed-auth?token=...` 写入会话。
**云端中控侧（`crypto_monitor/manual_trading_hub`）**
@@ -264,7 +313,7 @@ HUB_EMBED_ORIGINS=http://192.168.8.6:5070
将 `192.168.8.6:5070` 换成你本机访问 LocalNav 的完整 Origin（含协议与端口）。多台电脑可逗号分隔。
**四实例（币安/Gate/OKX）**：从中控点「实例 / 策略交易 / 复盘」时，**最新版**会由中控 `postMessage` 通知本地导航，在**同一层 iframe** 打开实例 SSO 链接（避免「导航 → 中控 → 实例」三层嵌套导致 Cookie 失效、反复要密码）。工具栏会出现 **「← 中控」** 返回监控区；刷新会由本地导航服务端代签新的 SSO 链接（须已配置 `NAV_HUB_USERNAME` / `NAV_HUB_PASSWORD`）。
**四实例（币安/Gate/OKX）**：从中控点「实例 / 策略交易 / 复盘」时，**最新版**会由中控 `postMessage` 通知本地导航，在**同一层 iframe** 打开实例 SSO 链接。工具栏会出现 **「← 中控」** 返回监控区与 **「实例免密」** 按钮；刷新会由本地导航服务端代签新的 SSO 链接（须已配置 `NAV_HUB_USERNAME` / `NAV_HUB_PASSWORD`）。
四实例 `.env` 建议：
@@ -276,57 +325,33 @@ HUB_EMBED_PARENT_ORIGINS=https://你的中控域名,http://192.168.x.x:5070
（`5070` 换成本地导航实际地址；与中控相同的 `HUB_BRIDGE_TOKEN` 必填。）
### 8.7 gate_scout_order（Gate 扫单）接入
### 9.8 Gate 服务 iframe 代登录（手动配置）
**gate_scout 通常部署在云服务器**；本地导航在本机/局域网，通过 iframe 打开云上面板（不是 `127.0.0.1`）。
本版本**不再自动创建**「Gate 扫单」分组。若需内嵌 Gate 扫描端或执行器，请在 **服务管理** 中手动添加服务，**嵌入类型** 选「Gate 扫描端」或「Gate 执行器」。
**1. 云上**（Nginx 反代示例）：
| 服务 | 本机端口 | 建议对外 |
|------|----------|----------|
| 扫描端 | 8088 | `https://scout.你的域名` → `127.0.0.1:8088` |
| 执行器 | 8090 | `https://exec.你的域名` → `127.0.0.1:8090` |
进程环境变量（允许被本地导航嵌入）：
`.env` 配置示例：
```env
NAV_ALLOW_EMBED=true
NAV_EMBED_ORIGINS=http://192.168.8.6:5070
NAV_GATE_SCOUT_USERNAME=admin
NAV_GATE_SCOUT_PASSWORD=你的 Gate 密码
NAV_GATE_SCOUT_AUTO_LOGIN=1
```
`5070` 换成本地访问 LocalNav 的地址（可逗号分隔多个）。
打开对应服务时由本地服务端代登录；未开启自动登录时，可点工具栏 **「Gate 登录」** 手动触发。
**2. 本机 LocalNav `.env`：**
```env
NAV_SEED_GATE_SCOUT=1
NAV_GATE_SCOUT_UPDATE=1
NAV_GATE_SCOUT_SCHEME=https
NAV_GATE_SCOUT_SCOUT_HOST=scout.你的域名
NAV_GATE_EXECUTOR_HOST=exec.你的域名
NAV_GATE_SCOUT_PORT=443
NAV_GATE_EXECUTOR_PORT=443
```
若云上直接暴露端口、无子域名，可改用同一 `NAV_GATE_SCOUT_HOST=云IP或域名`，端口 `8088` / `8090`。
**3. 重启 LocalNav**，或在项目目录执行：
**清理旧数据（可选）**：若升级前已有自动种子创建的「Gate 扫单」分组，可执行：
```bash
NAV_SEED_GATE_SCOUT=1 NAV_GATE_SCOUT_UPDATE=1 python scripts/seed_gate_scout.py
python scripts/cleanup_gate_scout.py
```
也可在 **服务管理** 里手动改已有「Gate 扫描端」的主机与端口。
**4. 登录**：使用云上各服务 `config.yaml` 的 `auth` 账号密码。
---
## 九、部署指南（以 Ubuntu 为例）
## 十、部署指南（以 Ubuntu 为例）
以下假设：系统为 **Ubuntu 20.04/22.04/24.04** 等，项目路径为 **`/opt/LocalNav`**，监听端口 **5070**，进程以 **root** 用户运行；可根据实际域名与端口修改。
### 9.1 系统准备
### 10.1 系统准备
```bash
sudo apt update
@@ -335,7 +360,7 @@ sudo apt install -y python3 python3-venv python3-pip git
（若已安装 Python 3、venv 与 git，可跳过。）
### 9.2 克隆项目并安装依赖
### 10.2 克隆项目并安装依赖
```bash
sudo mkdir -p /opt
@@ -358,7 +383,7 @@ pip install -r requirements.txt -i https://pypi.org/simple
sudo systemctl restart nav-site
```
### 9.3 配置密钥（必做）
### 10.3 配置密钥（必做）
```bash
sudo mkdir -p /etc/nav-site
@@ -370,7 +395,7 @@ sudo chmod 600 /etc/nav-site/secret_key
**替代做法**：也可在项目根目录放置 `.env`（建议 `chmod 600 .env`），`WorkingDirectory` 指向项目根时程序会自动加载。若 systemd 的 `Environment` / `EnvironmentFile` 里已设置同名变量，**以 systemd 为准**（`.env` 不会覆盖已有环境变量）。
### 9.4 使用 systemd 常驻运行（推荐）
### 10.4 使用 systemd 常驻运行（推荐）
创建服务文件（仍使用内置 `python app.py` 时示例；若改用 Gunicorn，将 `ExecStart` 改为 gunicorn 命令即可）：
@@ -428,7 +453,7 @@ sudo systemctl status nav-site
journalctl -u nav-site -f
```
### 9.5 防火墙（若启用了 ufw）
### 10.5 防火墙（若启用了 ufw）
```bash
sudo ufw allow 5070/tcp
@@ -441,7 +466,7 @@ sudo ufw reload
sudo ufw allow from 192.168.0.0/16 to any port 5070 proto tcp
```
### 9.6 可选：使用 Gunicorn 提高稳定性
### 10.6 可选：使用 Gunicorn 提高稳定性
安装：
@@ -458,7 +483,7 @@ ExecStart=/opt/LocalNav/.venv/bin/gunicorn -w 2 -b 0.0.0.0:5070 app:app
说明：`-w 2` 为 worker 数量，可按机器 CPU 调整；`app:app` 表示 `app.py` 中的全局变量 `app`。
### 9.7 使用 PM2 守护进程（可选）
### 10.7 使用 PM2 守护进程（可选）
适合已安装 [PM2](https://pm2.keymetrics.io/) 的环境（常见于用 Node 的服务器上顺带托管 Python 进程）。项目根目录提供 **`ecosystem.config.cjs`**，用虚拟环境里的 Python 直接运行 **`app.py`**（与手动 `python app.py` 一致），**实例数固定为 1**（Flask 内置开发服务器不宜多进程监听同一端口）。
@@ -508,7 +533,7 @@ pm2 startup
**说明**：若 `interpreter` 指向的 `.venv/bin/python` 不存在，PM2 会启动失败；请确认虚拟环境路径与 `ecosystem.config.cjs` 中一致。Windows 下脚本会自动使用 `.venv\Scripts\python.exe`。
### 9.8 外网 HTTPS 访问（Nginx 反向代理）
### 10.8 外网 HTTPS 访问（Nginx 反向代理）
若需从 **公网或外网** 通过 **HTTPS** 访问本导航站（浏览器地址栏为 `https://`），建议在 Ubuntu 上用 **Nginx** 终止 TLS，反代到本机 `127.0.0.1:5070`。Flask 仍监听内网端口，不直接暴露 5070 到公网。
@@ -597,15 +622,16 @@ sudo ufw reload
---
## 十、数据与备份
## 十一、数据与备份
- 默认数据库文件：**`nav_local.db`**，位于 **启动进程时的当前工作目录**（与 `WorkingDirectory` 一致）。
- 备份：定期复制该文件即可（建议在服务停止或负载极低时复制，避免损坏）。
- 恢复：替换同名文件后重启服务。
- **推荐**：登录后进入 **「系统设置」** → **一键备份** 下载数据库文件。
- **恢复**：在「系统设置」上传 `.db` 文件一键恢复（恢复前会自动生成 `.bak` 备份）；**恢复后请重启服务**。
- 也可手动复制 `nav_local.db` 做备份；恢复时替换同名文件后重启服务。
---
## 十一、路由一览（便于排障与二次开发）
## 十二、路由一览（便于排障与二次开发）
| 路径 | 说明 |
|------|------|
@@ -620,10 +646,15 @@ sudo ufw reload
| `/admin/services/new` | 新建服务 |
| `/admin/services/<id>/edit` | 编辑服务 |
| `/admin/services/<id>/delete` | 删除服务（POST） |
| `/admin/settings` | 系统设置（改密、备份恢复） |
| `/admin/settings/backup` | 下载数据库备份 |
| `/api/embed/hub-login` | 中控代登录（自动登录用） |
| `/api/embed/gate-scout-login` | Gate 服务代登录 |
| `/api/embed/hub-instance-url` | 实例 SSO 免密签发 |
---
## 十二、常见问题（FAQ）
## 十三、常见问题（FAQ）
**Q：手机能打开吗？**
能。只要手机与服务器在同一局域网，且防火墙放行端口，浏览器访问 `http://服务器IP:端口` 即可。
@@ -635,20 +666,20 @@ sudo ufw reload
设置环境变量 `NAV_PORT=8080`（示例）后重启进程；防火墙与 Nginx `proxy_pass` 端口需一并修改。默认端口为 **5070**。
**Q：忘记密码怎么办？**
若有服务器文件权限，可用 SQLite 工具修改 `users` 表，或删除用户行后通过代码逻辑重新种子用户（需具备运维或开发能力）。
登录后进入 **「系统设置」** 修改密码（须记得当前密码）。若完全无法登录，可用 SQLite 工具修改 `users` 表，或删除用户行后重启让程序按 `.env` 重新创建管理员。
**Q：能否从外网访问？**
可以。推荐在 Ubuntu 上用 **Nginx + HTTPS** 反代到 `127.0.0.1:5070`，并配置 `NAV_TRUST_PROXY=1` 等变量，详见 **9.8 外网 HTTPS 访问**。请务必使用强密码并做好访问控制。
可以。推荐在 Ubuntu 上用 **Nginx + HTTPS** 反代到 `127.0.0.1:5070`，并配置 `NAV_TRUST_PROXY=1` 等变量，详见 **10.8 外网 HTTPS 访问**。请务必使用强密码并做好访问控制。
---
## 十三、版本与维护
## 十四、版本与维护
- 依赖版本见 `requirements.txt`；升级依赖前建议在测试环境验证。
- 修改模板或静态文件后，重启进程即可生效；修改 Python 代码同样需要重启（`NAV_DEBUG=1` 时开发服务器可自动重载，但不建议在生产长期开启）。
---
**文档结束。** 若你后续增加「HTTPS 链接」「新窗口打开」「修改密码」等功能，建议在本文档对应章节补充说明并保持与代码一致。
**文档结束。**
**仓库地址：** https://git.bz121.com/dekun/LocalNav.git