From 33564fb8f597d45116632fae0e823af665033ac5 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 8 Sep 2026 22:39:52 +0800 Subject: [PATCH] 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 --- .env.example | 15 +++- README.md | 171 +++++++++++++++++++++++++++++++++------------ docker-compose.yml | 30 +++++--- 3 files changed, 162 insertions(+), 54 deletions(-) diff --git a/.env.example b/.env.example index 05b2e82..e30da55 100644 --- 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= diff --git a/README.md b/README.md index 4e0813b..5209f26 100644 --- 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@:220//HomeDash.git +# 1. 拉取仓库（把 换成你自己的 Git 托管地址） +git clone 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://:3003" ``` -访问 `http://: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= \ + -e NAVI_ADMIN_TOKEN= \ + -v $PWD/data:/app/data \ + jianf-navi +``` + +### 首次配置导航项 + +容器启动后按需编辑 `data/conf.yml`（sections 列表），或直接用管理后台添加： + +```bash +# 先让 conf.yml 从模板生成 docker compose restart +# 或用管理 WebUI 在浏览器添加：http://: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 -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": "", "serverPort": 7000, - "auth": { "method": "token", "token": "frp-token" }, + "auth": { "method": "token", "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 = "" +serverPort = 7000 + +auth.method = "token" +auth.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） diff --git a/docker-compose.yml b/docker-compose.yml index b2d0684..0d2da39 100644 --- 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://: +# +# ── 国内网络注意 ── +# SearXNG 需访问 Google/Bing 等引擎。若服务器出不了外网， +# 编辑 searxng-settings.yml 的 outgoing.proxies 填你的代理： +# proxies: +# all://: http://: +# 再 docker compose up -d --build 重新构建。