docs: complete deployment tutorial + frp/webui4frpc guide, expand .env/docker-compose for tokens & base_url

- Rewrite quick-start for source clone & build (A: compose, B: docker run) - Expand frp section: full frps.toml, webui4frpc WebUI workflow, native frpc.toml, tunnel planning table - docker-compose: NAVI_PORT / SEARXNG_BASE_URL env passthrough, better docs - .env.example: document all vars incl token generation & base_url - Fix firefox debugging URL typo, extension token note
2026-09-08 22:39:52 +08:00
parent f0b318be45
commit 33564fb8f5
3 changed files with 162 additions and 54 deletions
--- a/.env.example
+++ b/.env.example
@ -1,8 +1,17 @@
 # JianF 统一导航服务环境变量
-# 复制此文件为 .env 并修改
+# 复制此文件为 .env 并修改，然后 docker compose up -d

-# 浏览器插件同步令牌（留空则不鉴权）
+# 宿主机对外端口（Dashy/搜索/管理统一入口）
+NAVI_PORT=3003
+
+# 对外访问地址（浏览器打开的域名/地址，影响搜索结果页与跳转链接）
+# 有公网域名填 https://nav.example.com
+# 纯内网用 http://<内网IP>:3003
+SEARXNG_BASE_URL=http://localhost:3003
+
+# 浏览器插件同步令牌（建议生成随机长串；插件设置里要填同一个值）
+# 生成: openssl rand -hex 24
 NAVI_SYNC_TOKEN=

-# 管理 API 令牌（留空则不鉴权）
+# 管理后台/API 写操作令牌（建议生成随机长串）
 NAVI_ADMIN_TOKEN=
--- a/README.md
+++ b/README.md
@ -45,36 +45,53 @@ Dashy / SearXNG(→Clash 代理出网) / 历史 API / 管理 UI

 ### 前置条件

- Docker + Docker Compose v2
- 可选：反向代理（Nginx / Caddy / Traefik）用于 HTTPS
+- Docker 20+ 与 Docker Compose v2
+- 可选：公网域名 + 反向代理，用于外网访问（见下文「生产部署」）

-### 1. 克隆并启动
+### 方式 A：从本仓库拉取源码构建（推荐）

 ```bash
-git clone ssh://git@<your-gitea>:220/<owner>/HomeDash.git
+# 1. 拉取仓库（把 <your-gitea> 换成你自己的 Git 托管地址）
+git clone <repo-url> HomeDash
 cd HomeDash
-cp .env.example .env   # 编辑令牌
-docker compose up -d
+
+# 2. 配置环境变量
+cp .env.example .env
+#   编辑 .env：
+#   - NAVI_SYNC_TOKEN / NAVI_ADMIN_TOKEN：鉴权令牌，openssl rand -hex 24 生成
+#   - SEARXNG_BASE_URL：对外访问地址（有域名填 https://nav.example.com）
+#   - NAVI_PORT：对外端口（默认 3003）
+
+# 3. 首次启动（会拉取 golang/dashy/searxng 基础镜像并编译）
+docker compose up -d --build
+
+# 4. 访问
+echo "打开 http://<ip>:3003"
 ```

-访问 `http://<your-ip>:3003`
-
-### 2. 首次配置
-
-编辑 `data/conf.yml` 自定义导航项，重启生效：
+### 方式 B：直接构建镜像运行

 ```bash
+docker build -t jianf-navi .
+docker run -d --name jianf-navi -p 3003:8080 \
+  -e SEARXNG_BASE_URL=https://nav.example.com \
+  -e NAVI_SYNC_TOKEN=<random> \
+  -e NAVI_ADMIN_TOKEN=<random> \
+  -v $PWD/data:/app/data \
+  jianf-navi
+```
+
+### 首次配置导航项
+
+容器启动后按需编辑 `data/conf.yml`（sections 列表），或直接用管理后台添加：
+
+```bash
+# 先让 conf.yml 从模板生成
 docker compose restart
+# 或用管理 WebUI 在浏览器添加：http://<ip>:3003/admin/
 ```

-### 3. 导入预构建镜像（可选）
-
-如果无法构建，使用预导出的镜像：
-
-```bash
-docker load < navi-image.tar.gz
-docker compose up -d
-```
+> 首次没有 data/ 目录时，容器会用内置 `conf.example.yml` 生成一份最小配置。

 ## 配置说明

@ -112,8 +129,10 @@ icon: fas fa-star    # Font Awesome

 | 变量 | 说明 | 默认 |
 |------|------|------|
-| `NAVI_SYNC_TOKEN` | 浏览器插件同步令牌 | 空（不鉴权） |
-| `NAVI_ADMIN_TOKEN` | 管理后台写操作令牌 | 空（不鉴权） |
+| `NAVI_SYNC_TOKEN` | 浏览器扩展同步历史令牌 | 空（不鉴权） |
+| `NAVI_ADMIN_TOKEN` | 管理后台/API 写操作令牌 | 空（不鉴权） |
+| `SEARXNG_BASE_URL` | 对外访问地址，影响搜索结果链接 | `http://localhost:3003` |
+| `NAVI_PORT` | compose 对外端口 | `3003` |

 ## 浏览器扩展

@ -121,7 +140,9 @@ icon: fas fa-star    # Font Awesome

 **Chrome / Edge**：`chrome://extensions/` → 开发者模式 → 加载 `extension/chrome/`

-**Firefox**：`about:debugwriting#/runtime/this-firefox` → 加载 `extension/firefox/manifest.json`
+**Firefox**：`about:debugging#/runtime/this-firefox` → 临时加载 `extension/firefox/manifest.json`
+
+> 扩展的「同步令牌」需填服务端 `.env` 里 `NAVI_SYNC_TOKEN` 的**同一个值**，否则同步被拒(401)。

 ### 配置

@ -275,67 +296,131 @@ location /search { auth_request off; proxy_pass $backend; }

 > [webui4frpc](https://gitcode.com/JianFeeeee/webui4frpc) — 基于 Go 与 Web 的可视化 frpc 配置管理工具，
 > 提供 WebUI 创建/启停 frpc 隧道，无需手写 frpc.toml。
+> 也可不用它，直接用原生 frpc（见文末「原生 frpc 方式」）。

-### 拓扑
+### 为什么要穿透
+
+本导航容器跑在**内网**（如 192.168.x.x:3003）。要让**外网通过域名访问**，需要：

 ```
-公网用户 → 阿里云 VPS frps(7000/8080/443) → frpc ← webui4frpc(内网:7500) 管理
-        → portal-nginx(内网) 认证分流 → navi:3003
+外网用户
+  → 公网 VPS(有公网IP) 上的 frps        [frp 服务端，监听控制端口 + 域名端口]
+  → frpc（内网运行，webui4frpc 管理或原生）
+  → 你内网的 portal-nginx / navi        [把域名流量转发进来]
 ```

-### 1. 公网 VPS 部署 frps
+### 第 1 步：公网 VPS 部署 frps

-```bash
+下载 frp 服务端二进制并写配置：
+
+```toml
 # frps.toml
-bindPort = 7000
-vhostHTTPPort = 8080
-# ...按需配置 auth.token 与 TLS
+bindPort = 7000              # frpc 连接 frps 的控制端口
+vhostHTTPPort = 8080         # HTTP 类型代理的入口端口（雷池/WAF 也走它）
+
+auth.method = "token"
+auth.token = "<长随机token>"  # frpc 必须带相同 token 才能连
+
+tls.enable = true            # frpc↔frps 加密
+
+# 用 systemd 启动，或直接:
+# ./frps -c frps.toml
 ```

-### 2. 内网主机部署 webui4frpc
+VPS 安全组/防火墙需放行：`7000`(frpc连接)、`8080`(http域名)、`443/80`(若 https 由 frps 终结)。
+
+### 第 2 步：内网主机部署 webui4frpc（可视化）
+
+从 [webui4frpc](https://gitcode.com/JianFeeeee/webui4frpc) 下载二进制，启动：

 ```bash
 /opt/webui4frpc/webui4frpc \
  -addr 0.0.0.0:7500 \
-  -user <admin> -password <强密码> \
+  -user admin -password '<强密码>' \
  -workdir /opt/webui4frpc/data
+# 打开 http://<内网IP>:7500 进入 WebUI
 ```

-### 3. 在 WebUI 中创建隧道
+### 第 3 步：在 WebUI 建「portal」隧道

-webui4frpc 把配置存为 `configs/*.json`。一个隧道文件示例：
+在 WebUI 里新建配置，指向公网 frps，并添加代理。等价配置文件存于 `configs/*.json`：

 ```json
 {
  "serverAddr": "<vps-public-ip>",
  "serverPort": 7000,
-  "auth": { "method": "token", "token": "frp-token" },
+  "auth": { "method": "token", "token": "<frp-token>" },
  "proxies": [
    {
      "name": "portal_https",
      "type": "https",
-      "localIP": "192.168.1.100",
+      "localIP": "<内网portal-nginx主机IP>",
      "localPort": 3080,
-      "customDomains": ["*.navi.example.com", "navi.example.com"]
+      "customDomains": ["*.nav.example.com", "nav.example.com"]
    },
    {
      "name": "portal_http",
      "type": "tcp",
-      "localIP": "192.168.1.100",
+      "localIP": "<内网portal-nginx主机IP>",
      "localPort": 3081,
      "remotePort": 8080
+    },
+    {
+      "name": "navi_ssh",
+      "type": "tcp",
+      "localIP": "<内网目标主机IP>",
+      "localPort": 22,
+      "remotePort": 220
    }
  ]
 }
 ```

- `type: https` + `customDomains` → frps 把 443 的域名流量转发给内网 portal-nginx 的 3080（TLS 终止在内网）
- `type: tcp` 用于无域名的端口映射（如 Gitea SSH、HTTP 跳转）
+webui4frpc 会自动下载并启动 `frpc`（存 `data/bin/`），配置变更即热加载。

-### 4. frpc 客户端生成
+### 第 4 步：DNS 解析

-webui4frpc 自动下载并启动 `frpc` 二进制（`data/bin/`），配置变更后热加载。
-多份配置 = 多个 frpc 进程，各自连接 frps。
+把 `nav.example.com`、`*.nav.example.com` 的 DNS 指向**公网 VPS IP**。
+
+- `type: https` 代理：frps 把域名 443 流量转发内网 portal-nginx:3080，**TLS 证书由你内网管理**
+- `type: tcp`（portal_http）：把外网 8080 → 内网 3081（HTTP→HTTPS 跳转或备用入口）
+
+### 原生 frpc 方式（不用 webui4frpc）
+
+```toml
+# frpc.toml
+serverAddr = "<vps-public-ip>"
+serverPort = 7000
+
+auth.method = "token"
+auth.token = "<frp-token>"
+
+[[proxies]]
+name = "portal_https"
+type = "https"
+localIP = "192.168.1.100"
+localPort = 3080
+customDomains = ["nav.example.com", "*.nav.example.com"]
+
+[[proxies]]
+name = "portal_http"
+type = "tcp"
+localIP = "192.168.1.100"
+localPort = 3081
+remotePort = 8080
+```
+
+```bash
+./frpc -c frpc.toml
+```
+
+### 隧道规划对照
+
+| 代理名 | type | 本地 | 远端 | 用途 |
+|--------|------|------|------|------|
+| portal_https | https | 内网:3080 | 443域名 | 统一反代 HTTPS 入口 |
+| portal_http | tcp | 内网:3081 | 8080 | HTTP 跳 HTTPS / 备用 |
+| gitea_ssh | tcp | 内网:22 | 220 | Git SSH |

 ## 鉴权（历史同步 + 管理 API）

--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -7,16 +7,23 @@ services:
    image: jianf-navi:latest
    restart: unless-stopped
    ports:
-      - "3003:8080"
+      # 宿主机端口:容器内 nginx 端口（Dashy/搜索/管理 统一入口）
+      - "${NAVI_PORT:-3003}:8080"
    volumes:
+      # 持久化：导航配置 conf.yml + 历史 history.json + 图标 item-icons/
      - ./data:/app/data
    environment:
-      # 设置后，浏览器插件同步和管理 UI 的写操作需要此令牌
+      # ---- 鉴权令牌（强烈建议设置）----
+      # 浏览器扩展同步历史用
      - NAVI_SYNC_TOKEN=${NAVI_SYNC_TOKEN:-}
-      # 设置后，管理 API 的写操作需要此令牌
+      # 管理后台/API 写操作用
      - NAVI_ADMIN_TOKEN=${NAVI_ADMIN_TOKEN:-}
+
+      # ---- 对外访问地址（公网域名，影响搜索结果页链接）----
+      # 例如 https://nav.example.com （不含 /search 子路径）
+      - SEARXNG_BASE_URL=${SEARXNG_BASE_URL:-http://localhost:3003}
    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/healthz"]
+      test: ["CMD", "curl", "-fs", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 5s
      start_period: 30s
@ -26,7 +33,14 @@ services:
        limits:
          memory: 512M

-# 使用方式：
-# 1. 复制 .env.example 为 .env 并修改
-# 2. docker compose up -d
-# 3. 访问 http://your-ip:3003
+# ── 使用方式 ──
+# 1. cp .env.example .env，编辑令牌与域名
+# 2. docker compose up -d --build
+# 3. 访问 http://<ip>:<NAVI_PORT>
+#
+# ── 国内网络注意 ──
+# SearXNG 需访问 Google/Bing 等引擎。若服务器出不了外网，
+# 编辑 searxng-settings.yml 的 outgoing.proxies 填你的代理：
+#   proxies:
+#     all://: http://<proxy-ip>:<port>
+# 再 docker compose up -d --build 重新构建。