[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-105329":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":10,"trendingCount":16,"starSnapshotCount":16,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},105329,"miku-gate","vioIetMiku\u002Fmiku-gate","vioIetMiku","将VPN Gate 公益家宽挂载到vps，实现一机多家宽出口的效果，端口隔离 节点互不影响 支持链式代理 导入指纹浏览器","",null,"Go",77,3,52,1,0,10,30,63.81,"MIT License",false,"main",[],"2026-11-01 00:14:23","# Miku Gate\n\n## VPN Gate 是什么？\n\n[VPN Gate](https:\u002F\u002Fwww.vpngate.net\u002F) 是日本筑波大学开展的学术实验项目，由世界各地志愿者提供公共 VPN 中继。Miku Gate 使用其公开的 OpenVPN 配置，为自己的 Linux VPS 管理多个出口。\n\nVPN Gate 不属于 Miku Gate。节点数量、国家、在线时间随时变化，**不保证住宅 IP、固定出口、在线率或严格隐私，也不是无日志服务**。请阅读[官方介绍](https:\u002F\u002Fwww.vpngate.net\u002Fen\u002Fabout_overview.aspx)与[日志和反滥用政策](https:\u002F\u002Fwww.vpngate.net\u002Fen\u002Fabout_abuse.aspx)，遵守当地法律与服务商规则。\n\n## 感谢 fanout\n\n特别感谢 **[byJoey\u002Ffanout](https:\u002F\u002Fgithub.com\u002FbyJoey\u002Ffanout)**。Miku Gate 基于其按国家批量出口、网络命名空间隔离和自动重连能力，再加入 Miku 界面、多格式订阅、终端一键配置、Docker 与前后端分离。\n\n基线提交：`d7ce5224caf3469b19876982abdf8d1be16c4a8b`。原 MIT 许可证和作者署名保留，见 [LICENSE](LICENSE)、[上游说明](README.fanout.md) 与 [源码来源](PROVENANCE.md)。\n\n\u003Cp align=\"center\">\u003Cimg src=\"src\u002Fassets\u002Fmiku-hero-v1.png\" alt=\"Miku Gate 插画\" width=\"260\">\u003C\u002Fp>\n\u003Ch2 align=\"center\">世界，等你连接。\u003C\u002Fh2>\n\n**代码版本：v0.2.6**，正式状态以 [Releases](https:\u002F\u002Fgithub.com\u002FvioIetMiku\u002Fmiku-gate\u002Freleases\u002Flatest) 为准。支持 Linux amd64 \u002F arm64；完整安装包已编译，VPS 无需安装 Go。\n\n## 先选一种安装方式，不要把下面的命令全部执行\n\n**原来的原生一键安装完整保留，Docker 是新增选项，不是替代原生安装。**\n\n| 你想怎么用 | 选择哪一节 | 是否要 Docker | 安装后的管理命令 |\n| --- | --- | --- | --- |\n| 直接装在 VPS 上，使用面板和 miku 菜单 | [方式一：原生一键安装](#install-native) | 不需要 | `miku`、`miku info`、`miku quick` |\n| 在一台 VPS 上用 Docker，同时运行独立前端和后端 | [方式二：Docker 同机部署](#install-docker) | 需要 | 在部署目录运行 `bash install-docker.sh ...` |\n| 后端在 VPS A，前端放到服务器 B | [方式三：跨服务器部署](#install-remote) | 两台都需要 | A 管后端；B 运行 `python3 -B scripts\u002Ffrontend.py ...` |\n| 不想在线运行脚本，自己下载并上传安装文件 | [方式四：手动安装](#install-offline) | 取决于选择的模式 | 仍分别使用原生或 Docker 的管理命令 |\n\n\n## 方式一：原生一键安装（推荐）\n\n这条路线**不需要 Docker、Compose、Node.js，也不需要提前安装 Go**。程序安装到 VPS，由 systemd \u002F OpenRC 管理；网页由后端内嵌提供。\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FvioIetMiku\u002Fmiku-gate\u002Fmain\u002Fmikugate.sh)\n```\n\n**作用：**下载最新正式包、验证 SHA256 和文件清单，准备系统依赖和核心，然后安装、启动原生服务。这个命令不带 `--docker`，不会部署 Docker 容器。\n\n### 第 2 步：按提示选择使用方式\n\n安装完成后，交互菜单提供：\n\n- 输入 **1**：使用网页面板管理。适合先登录页面，再添加出口、配置域名和查看节点。\n- 输入 **2** 或直接回车：进入终端一键配置。随后询问节点域名；没有域名直接回车，使用 REALITY。\n\n这两个选项只是**同一个原生服务的操作方式**，不是两种不同安装，不需要再次安装。\n\n如果一开始就确定只想使用面板，可以用下面这条**代替第 1 步**，不要把两条都跑一遍：\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FvioIetMiku\u002Fmiku-gate\u002Fmain\u002Fmikugate.sh) --panel\n```\n\n如果想不填写节点域名、立即开始后台一键配置，也可以用这条**代替第 1 步**：\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FvioIetMiku\u002Fmiku-gate\u002Fmain\u002Fmikugate.sh) --quick --no-domain --background\n```\n\n`--quick` 表示安装后启动一键配置；`--no-domain` 使用 REALITY；`--background` 表示输出当前可用结果后返回终端，后台继续准备节点。\n\n### 第 3 步：查看管理地址和登录口令\n\n**在哪里做：**同一台 VPS root Bash，任意目录。\n\n```bash\nmiku info\n```\n\n**作用：**重新打印实际管理地址和访问口令。浏览器打开输出的**完整地址，包括端口与随机路径**，例如 `http:\u002F\u002FVPS_IP:实际端口\u002F随机路径\u002F`。不要把例子里的文字照抄，不要只访问 VPS IP 或根目录。\n\n打开网页之前，到服务商安全组及宿主防火墙放行 **info 显示的实际管理端口**。建立节点后，节点入口 \u002F 代理端口还需要分别放行；管理端口开放不等于节点端口已开放。\n\n### 第 4 步：创建节点，拿到订阅\n\n可在网页中选择国家、数量和入口模板创建出口，也可以在 VPS 运行：\n\n```bash\nmiku quick\n```\n\n**作用：**询问节点域名并启动后台配置，默认目标为日本 5、韩国 3、美国 3 个**成功且入口就绪**的节点。域名留空使用 REALITY；填写域名时需要 DNS 指向 VPS，并满足证书签发条件。公共节点不足时会继续尝试，不保证马上凑齐。\n\n查看当前可用订阅和节点链接：\n\n```bash\nmiku sub\n```\n\n**作用：**输出订阅及当前可用节点，把对应客户端支持的订阅地址导入客户端。地址包含访问凭据，不要公开分享。\n\nCtrl+C 只退出终端等待，不会停止后台补齐；要停止补齐但保留已成功节点：\n\n```bash\nmiku quick --stop\n```\n\n### 第 5 步：原生版日常管理\n\n以下命令都在**原生安装所在 VPS**执行，任意目录即可；不要把它们当作 Docker 维护命令。\n\n| 命令 | 做什么 |\n| --- | --- |\n| `miku` | 打开快捷菜单 |\n| `miku info` | 查看管理地址和口令 |\n| `miku status` | 查看服务是否运行 |\n| `miku password` | 重置管理口令 |\n| `miku domain` | 绑定、更换或解绑后端管理域名；不是设置独立前端 HTTPS |\n| `miku port` | 修改后端管理端口；改后重新运行 info |\n| `miku quick` \u002F `miku sub` | 一键配置节点 \u002F 查看订阅 |\n| `miku logs` | 查看服务日志，安装或连接异常时先看这里 |\n| `miku restart` | 重启服务，现有连接可能暂时中断 |\n| `miku backup` | 生成停机一致性备份；完成后恢复原运行状态 |\n| `miku uninstall` | 停止并取消自启，保留程序和数据 |\n\n`miku purge` \u002F `miku uninstall --purge` 是**删除本服务数据和备份**的破坏性操作，不是普通更新命令；只有明确要清空时才使用。\n\n\u003Ca id=\"install-docker\">\u003C\u002Fa>\n\n## 方式二：Docker 同机部署（独立前端 + 后端）\n\nDocker 是可选方式。已经选择上面的原生安装，就不用再执行这一节。\n\n### 第 1 步：先装好 Docker、Compose 和 Python\n\n**在哪里做：**要运行 Docker 后端的 Linux VPS。\n\n按发行版阅读官方说明：\n\n- [Docker Engine 安装总览](https:\u002F\u002Fdocs.docker.com\u002Fengine\u002Finstall\u002F)\n- [Ubuntu 官方步骤](https:\u002F\u002Fdocs.docker.com\u002Fengine\u002Finstall\u002Fubuntu\u002F) \u002F [Debian 官方步骤](https:\u002F\u002Fdocs.docker.com\u002Fengine\u002Finstall\u002Fdebian\u002F)\n- [Compose 插件安装（docker compose）](https:\u002F\u002Fdocs.docker.com\u002Fcompose\u002Finstall\u002Flinux\u002F)，不是旧版独立的 `docker-compose`。\n\n官方仓库安装方案可一并安装 `docker-compose-plugin`。已经安装过且能正常运行，就不必重装。检查：\n\n```bash\ndocker info\ndocker compose version\npython3 --version\n```\n\n**看到什么才算准备好：**Docker Engine 可连接、Compose 命令正常、Python 版本至少 **3.10**。Miku 安装入口不会替你安装 Docker Engine。\n\n后端使用 host 网络、privileged 和 TUN，能够影响宿主网络；要求 rootful Docker，不支持 rootless \u002F Docker Desktop。前端则是非特权、只读 Nginx；两端权限不同。\n\n### 第 2 步：只运行 Docker 安装命令\n\n**在哪里做：**同一台 VPS root Bash，当前目录不限。\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FvioIetMiku\u002Fmiku-gate\u002Fmain\u002Fmikugate.sh) --docker\n```\n\n**作用：**验证正式安装包，将部署文件保存到 `\u002Fopt\u002Fmiku-gate-docker`，构建或复用后端镜像，再启动后端与独立前端。v0.2.6 中默认就是分离部署，不需要另外再装一套前端。\n\n首次可能要下载基础镜像、系统依赖和核心。后续文件输入未变化时可复用已标记镜像；不要把首次构建等待误认为脚本已经无响应。\n\n### 第 3 步：进入部署目录，确认两端状态\n\n**在哪里做：**安装后的 VPS。与原生 `miku` 不同，宿主 Docker 维护脚本需在项目目录运行。\n\n```bash\ncd \u002Fopt\u002Fmiku-gate-docker\nbash install-docker.sh status\nbash install-docker.sh frontend info\nbash install-docker.sh backend info\n```\n\n- `cd`：进入部署文件、.env 和持久化数据所在目录。\n- `status`：查看前端与后端容器状态。\n- `frontend info`：显示浏览器应打开的**独立前端完整地址**。\n- `backend info`：显示后端地址和访问口令。前端登录用这个口令，不另建账号。\n\n浏览器打开前端 info 的完整地址，并放行输出的实际前端端口。后端首次优先 8899、前端优先 8900，但冲突会自动换端口，**不要固定认为一定是这两个端口**。\n\n### 第 4 步：在网页或终端创建节点\n\n网页中的节点操作仍由后端执行。想用终端一键配置，在 `\u002Fopt\u002Fmiku-gate-docker` 运行：\n\n```bash\nbash install-docker.sh quick --no-domain --background\nbash install-docker.sh sub\n```\n\n第一条使用 REALITY 启动后台补齐；第二条查看当前订阅和可用节点。Docker 服务启停、更新、备份用 `install-docker.sh`，不要用宿主原生安装的 `miku update` 或 `miku backup`。\n\n### 第 5 步：确认访问路径与权限\n\n同机部署通常不必填写 `MIKU_BACKEND_URL`、`MIKU_BACKEND_BASE_PATH` 等参数；启动器会读取后端的实际端口、路径和 TLS 配置。只有跨服务器或特别指定后端时才手工填写。\n\n前端网页、登录、API 和订阅在同一源下访问；后端仍负责认证与数据。根路径 `\u002F` 返回 404 是随机路径保护，使用完整入口即可。\n\n## Docker 两端关系与独立管理\n\n```text\n浏览器 -> 独立 Nginx 前端（HTML\u002FCSS\u002FJS + 同源代理）\n                      -> Go 后端（认证\u002FAPI\u002F订阅\u002FVPN\u002F节点）\n                                      -> VPN Gate 出口\n```\n\n| 服务 | 配置 | 优先端口 | 权限 \u002F 挂载 |\n| --- | --- | --- | --- |\n| 后端 miku | compose.yaml | 8899 | privileged \u002F TUN；读写后端数据与证书 |\n| 前端 frontend | compose.frontend.yaml | 8900 | UID 101、只读、cap_drop ALL；仅公开资源和生成配置 |\n\n同机前端不必手填后端 URL \u002F 路径；保持对应变量为空，启动器读取真实配置：\n\n```bash\ncd \u002Fopt\u002Fmiku-gate-docker\nbash install-docker.sh up\nbash install-docker.sh frontend info\nbash install-docker.sh backend info\n```\n\n登录口令由后端维护，不需要在前端注册账号；前端不存后台密码，也不挂载后端私钥。根路径 404 属于随机路径保护，使用 info 打印的完整入口。\n\n### 独立启停与管理\n\n```bash\nbash install-docker.sh frontend start\nbash install-docker.sh frontend restart # 不重启后端 \u002F 节点\nbash install-docker.sh frontend check   # 只校验候选 Nginx 配置及资源\nbash install-docker.sh frontend info\nbash install-docker.sh frontend status\nbash install-docker.sh frontend logs\nbash install-docker.sh frontend stop\nbash install-docker.sh frontend down\nbash install-docker.sh backend status\nbash install-docker.sh backend logs\nbash install-docker.sh backend stop\nbash install-docker.sh backend start\n```\n\n顶层 `stop` \u002F `down` 处理两端；只停后端请带 backend，只停前端请带 frontend。quick\u002Fsub\u002Fpassword 仍操作后端，顶层 logs 默认看后端。\n\n## 自动端口与防火墙\n\n本节描述 Docker 前后两端。原生版不需要独立前端端口，实际管理端口以 `miku info` 为准。\n\n- 后端首次优先 8899，前端优先 8900；重启时优先保存的实际端口。\n- WEB_PORT \u002F MIKU_FRONTEND_PORT 是优先值，冲突会选择后续空闲端口，并避开已登记节点端口；IPv4 \u002F IPv6 都检查。\n- 合法范围 1024–65535；80、非整数、65536 等配置直接报错，不伪装为端口冲突。\n- 后端保存到 `docker-data\u002Fsettings.json`；前端保存到 `frontend\u002F.runtime\u002Fstate.json`，不用手改生成文件。\n- 以 info 打印的实际地址为准。自动选端口**不修改**云安全组、防火墙和外层反代上游。\n- 网页订阅走前端同源；终端 sub 使用后端发布地址，如需客户端可达，还要放行后端端口。节点入口 \u002F 代理端口分别放行。\n\n## 前端 HTTPS 与外层反向代理\n\n**在哪里做：前端所在的机器。** 同机部署就是那台 VPS；跨服务器部署就是前端服务器 B。下面以已经安装 Nginx 并持有有效证书为例，不会自动替你购买域名或签发外层证书。\n\n1. 先将前端域名的 DNS 记录指向前端服务器，准备匹配该域名的有效 HTTPS 证书。\n2. 进入前端项目目录，用 `nano .env` 或 `vi .env` 编辑以下设置并保存；前端内部只监听 loopback：\n\n```dotenv\nMIKU_FRONTEND_LISTEN=127.0.0.1\nMIKU_FRONTEND_PORT=\nMIKU_FRONTEND_ORIGIN=https:\u002F\u002Fpanel.example.com\n```\n\n```bash\npython3 -B scripts\u002Ffrontend.py restart\npython3 -B scripts\u002Ffrontend.py info\n```\n\n3. 上面两条命令在**前端包或完整项目的根目录**执行，两种包都支持：分别重新生成前端配置、打印实际监听地址。记下实际端口。\n4. 编辑已有外层 Nginx 的站点配置；使用 conf.d 的安装通常可新建 `\u002Fetc\u002Fnginx\u002Fconf.d\u002Fmiku-frontend.conf`。已有同域名站点时合并修改，不要重复创建冲突的 server。配置示例如下，**将 ACTUAL_FRONTEND_PORT 替换为上一步输出的实际端口**，域名和证书路径也改成自己的：\n\n```nginx\nserver {\n    listen 443 ssl;\n    server_name panel.example.com;\n    ssl_certificate \u002Fetc\u002Fletsencrypt\u002Flive\u002Fpanel.example.com\u002Ffullchain.pem;\n    ssl_certificate_key \u002Fetc\u002Fletsencrypt\u002Flive\u002Fpanel.example.com\u002Fprivkey.pem;\n    location \u002F {\n        proxy_pass http:\u002F\u002F127.0.0.1:ACTUAL_FRONTEND_PORT;\n        proxy_set_header Host $host;\n        proxy_set_header X-Forwarded-Proto https;\n    }\n}\n```\n\n5. 保存站点配置后先检查语法；检查通过才加载。以下重载命令适用于 systemd 管理的 Nginx：\n\n```bash\nnginx -t && systemctl reload nginx\n```\n\n如果 Nginx 由 OpenRC、Docker 或其他管理器运行，使用该管理器的重载方式，不要套用 systemctl。`nginx -t` 失败时先修正报错，不要强制覆盖或关闭校验。\n\n6. 在浏览器打开前端公网 HTTPS 的**完整随机路径地址**。必须转发完整请求路径，不删除随机前缀。最终入口为 `https:\u002F\u002Fpanel.example.com\u002F真实随机路径\u002F`。Origin 只填源地址、不含随机路径；它决定浏览器来源校验和 Cookie Secure 标志，不要改成通配符。\n\n网页“管理域名 \u002F 证书”操作的是后端或节点，不是外层前端 TLS。前端 HTTPS 证书由外层反代维护。内部端口自动改变时，外层代理的上游也要手动同步。\n\n\u003Ca id=\"install-remote\">\u003C\u002Fa>\n\n## 方式三：前端部署到另一台服务器\n\n### 第 1 步：在后端 VPS A 安装后端\n\n**在哪里做：后端 VPS A。** 按“方式四”的步骤下载完整包、上传并解压，进入包内 `miku-gate` 目录，再执行：\n\n```bash\nbash install.sh --docker --backend-only\ncd \u002Fopt\u002Fmiku-gate-docker\nbash install-docker.sh backend info\n```\n\n**作用：**这组命令只部署后端，不启动前端；`backend info` 打印后端实际入口和登录口令。记录真实后端源地址和随机路径。例如 `https:\u002F\u002Fapi.example.com:9443\u002Fabc123\u002F` 只是格式示例，端口和路径必须换成 info 的结果。跨机建议使用 HTTPS，证书应被前端信任；自己的 CA 要加入前端镜像信任库，不能关闭 TLS 校验。\n\n### 第 2 步：在前端服务器 B 安装前端\n\n**在哪里做：另一台前端服务器 B，不是 VPS A。** 按“方式二第 1 步”准备 Linux Docker\u002FCompose 和 Python 3.10+；B 不需要 TUN、Go、后端程序或后端私钥。在 B 上上传前端专用包和 SHA256SUMS，进入这两个文件所在目录后运行：\n\n```bash\ngrep '  miku-gate-frontend-v0.2.6.tar.gz$' SHA256SUMS | sha256sum -c -\ntar --no-same-owner -xzf miku-gate-frontend-v0.2.6.tar.gz\ncd miku-gate\ncp -n .env.example .env\n```\n\n**上面四条命令依次是：**校验下载文件 → 解压 → 进入前端包目录 → 首次建立配置文件。已有 `.env` 不要覆盖。\n\n用你熟悉的编辑器打开前端机 B 的 `.env`（例如 `nano .env` 或 `vi .env`），将下面示例中的域名、后端端口、随机路径换成真实值，再保存。后端源地址与随机路径必须分开填写：\n\n```dotenv\nMIKU_FRONTEND_LISTEN=127.0.0.1\nMIKU_FRONTEND_PORT=\nMIKU_FRONTEND_ORIGIN=https:\u002F\u002Fpanel.example.com\nMIKU_BACKEND_URL=https:\u002F\u002Fapi.example.com:9443\nMIKU_BACKEND_BASE_PATH=\u002Fabc123\nMIKU_BACKEND_HOST=api.example.com:9443\n```\n\n```bash\npython3 -B scripts\u002Ffrontend.py start\npython3 -B scripts\u002Ffrontend.py info\n```\n\n**这两条命令的作用：**`start` 校验资源和 Nginx 配置后启动 B 上的前端容器，`info` 打印实际监听端口及完整访问地址。\n\n接着按“前端 HTTPS 与外层反向代理”一节在 B 上配置公网 HTTPS，代理到 info 显示的实际前端端口。用户打开 `https:\u002F\u002Fpanel.example.com\u002Fabc123\u002F`，输入后端生成的口令。服务器间只需要前端能访问后端管理接口，VPN 隧道和节点监听仍在后端 VPS。\n\n| 参数 | 填写方式 |\n| --- | --- |\n| MIKU_FRONTEND_ORIGIN | 浏览器访问的公网源，含协议和非标准公网端口，不含随机路径 |\n| MIKU_BACKEND_URL | 前端连接后端的源地址，不含随机路径 |\n| MIKU_BACKEND_BASE_PATH | 后端真实随机路径；确实无前缀时填 \u002F |\n| MIKU_BACKEND_HOST | 后端 Host \u002F TLS 校验域名，可带端口；通常与证书域名一致 |\n| MIKU_FRONTEND_PORT | 内部优先端口，留空记住实际端口、首次尝试 8900 |\n| MIKU_FRONTEND_LISTEN | IPv4 监听地址；有同机外层反代时建议 127.0.0.1 |\n\n不要把后端 .env、docker-data、证书私钥或另一台机器的 `.runtime` 整包复制到前端机。通过前端反代访问的用户会共享部分后端基于来源的登录冷却计数，避免反复尝试错误口令。\n\n### 后端改端口 \u002F 路径 \u002F 域名后怎么办？\n\n顶层 start\u002Frestart\u002Fupdate 会在后端就绪后同步同机前端。网页直接改后端配置、只操作 backend、或 Docker 自动重启后换了端口，需执行：\n\n```bash\nbash install-docker.sh frontend restart\nbash install-docker.sh frontend info\n```\n\n远程前端先更新本机 .env，再运行 `python3 -B scripts\u002Ffrontend.py restart`。本版没有后台配置监听器，不会自动发现远端路径改变。设置页的后端端口与路径不是前端监听设置，不要混淆。\n\n## 独立更新前端\n\n直接编辑 `frontend\u002Fpublic\u002F` 的 HTML\u002FCSS\u002FJS，无需重编译 Go。修改后：\n\n```bash\npython3 -B scripts\u002Fexport-frontend.py --refresh-manifest\npython3 -B scripts\u002Fexport-frontend.py\npython3 -B scripts\u002Ffrontend.py restart\n```\n\n默认 exporter **只校验、不覆盖**；`--from-backend` 才会用 Go 内嵌兼容页重新导入，可能覆盖分离版提示，使用前另存改动。前端没有 Node.js 运行依赖，国旗资源本地提供。\n\n启动器先校验资源与 Nginx 候选配置，通过后替换运行配置；失败保留旧配置，重建失败会恢复旧配置并尝试恢复旧实例。前端重启不会主动重启后端或已运行的节点。\n\n\u003Ca id=\"install-offline\">\u003C\u002Fa>\n\n## 方式四：下载文件后手动安装\n\n这是不想在线执行脚本时的替代方式，**不是原生 \u002F Docker 安装之后还要再做一次**。\n\n### 第 1 步：在本地下载，再上传到 VPS\n\n从 [v0.2.6 Release](https:\u002F\u002Fgithub.com\u002FvioIetMiku\u002Fmiku-gate\u002Freleases\u002Ftag\u002Fv0.2.6) 下载文件和 `SHA256SUMS`。该版本尚未发布时不要使用不存在的下载地址；可先使用你已经拿到的完整安装包，或等待正式发布。\n\n| 文件 | 用途 |\n| --- | --- |\n| `miku` | 单个自解压安装文件，含两种架构程序 |\n| `miku-gate-vps-v0.2.6.tar.gz` | VPS 完整安装包，含后端、独立前端、部署脚本 |\n| `miku-gate-v0.2.6.zip` | 完整源码和两种架构的安装程序 |\n| `miku-gate-frontend-v0.2.6.tar.gz` | 只有前端部署文件，给另一台前端服务器用 |\n| `install-online.sh` | 正式在线安装器，可先下载审阅 |\n| `SHA256SUMS` | 上述文件的校验值 |\n\n通过 SCP \u002F SFTP 上传到 VPS 的一个新目录。GitHub 自动生成的 “Source code” 压缩包**不等于**本项目上传的完整 ZIP，它不含已编译的 bin 文件。\n\n### 第 2 步：校验你实际下载的文件\n\n**在哪里做：**VPS 上，文件与 SHA256SUMS 放在同一目录。下面两组按你下载的文件二选一。\n\n使用单文件 `miku`：\n\n```bash\ngrep '  miku$' SHA256SUMS | sha256sum -c -\nbash miku --verify\n```\n\n使用 VPS tar.gz：\n\n```bash\ngrep '  miku-gate-vps-v0.2.6.tar.gz$' SHA256SUMS | sha256sum -c -\ntar --no-same-owner -xzf miku-gate-vps-v0.2.6.tar.gz\ncd miku-gate\n```\n\n**作用：**前一条检查下载文件完整性，后一条解压并进入包根目录。校验失败先重新下载，不要修改校验值绕过去。\n\n### 第 3 步：选择一种模式安装\n\n| 想要的模式 | 使用单文件 miku | 已进入 tar.gz \u002F ZIP 的 miku-gate 目录 |\n| --- | --- | --- |\n| 原生安装 | `bash miku` | `bash install.sh` |\n| Docker，默认两端分离 | `bash miku --docker` | `bash install.sh --docker` |\n| Docker，仅后端 | `bash miku --docker --backend-only` | `bash install.sh --docker --backend-only` |\n\n**这里只选一行执行。** 原生完成后用 `miku info`；Docker 完成后进入 `\u002Fopt\u002Fmiku-gate-docker`，运行 `bash install-docker.sh frontend info`。仅后端模式用 `backend info`，没有自动启动的独立前端。\n\n`--docker --split` 保留为本地完整包的兼容别名，默认 Docker 已分离；在线一键入口直接用 `--docker`，不必加 `--split`。想在以后给已有 Docker 后端补上前端，使用 `bash install-docker.sh frontend start` 即可。\n\n\n## 升级：原生和 Docker 分开操作\n\n### 原生安装升级\n\n**在哪里做：原生 Miku 所在 VPS，先保持旧服务及数据完好。**\n\n1. 在任意目录运行 `miku backup`，记录打印的备份文件，并复制到安全位置。\n2. 按“方式四”下载、校验新完整包，解压到一个新目录，进入其 `miku-gate` 目录。\n3. 在这个**新包目录**执行以下命令。它调用新版安装工具更新原来的固定安装位置，不会创建 Docker 服务，也不要求删除旧数据：\n\n```bash\nbash install.sh --update\nmiku status\nmiku info\n```\n\n三个命令依次为：保留配置更新原生服务 → 确认运行状态 → 获取当前登录地址。更新可能短暂中断节点连接。不要使用 `--reinstall` 或 `purge` 做普通升级。\n\n旧版 `miku update` 对包内文件数量有限制，本次含独立静态资源，旧原生安装推荐上述**新包 install.sh --update**流程。\n\n### 备份和保留哪些目录\n\n原生数据位于 `\u002Fvar\u002Flib\u002Fmiku`、程序位于 `\u002Fusr\u002Flocal\u002Flib\u002Fmiku`；Docker 数据位于其项目目录中的持久化子目录。两者不能混用备份命令或直接交换数据目录。\n\n\n### 从 Docker v0.2.5 升级\n\n1. 先在旧项目执行 `bash install-docker.sh backup`，另存 .env、反代配置和自定义前端文件。\n2. 下载并校验 v0.2.6 完整包，把新程序和部署文件更新到原项目目录；保留 docker-data、docker-certs、docker-backups 和 .env。\n3. 运行 `bash install-docker.sh update`。新版默认启动独立前端，用 frontend info 获取实际入口；只后端部署请用 backend update。\n\n不需要删除数据或 --reinstall。旧原生维护工具的 miku update 有包内文件数限制，**从旧原生版升级推荐解压新包后执行 `bash install.sh --update`**，不要用旧维护工具硬导入大包。新维护工具已提高有界清单上限，但仍做路径、权限和摘要验证。\n\n| 目录 | 用途 |\n| --- | --- |\n| docker-data\u002F | 口令、节点、订阅、核心与证书，敏感 |\n| docker-certs\u002F | Certbot 账户和私钥，敏感 |\n| docker-backups\u002F | 停机一致性备份，权限 600，敏感 |\n| frontend\u002Fpublic\u002F | 独立静态资源，可自行发布 |\n| frontend\u002F.runtime\u002F | 实际端口、路径和生成配置，不公开、不打包 |\n| .env | 部署设置，需要备份但不要公开 |\n\n```bash\nbash install-docker.sh backup\nbash install-docker.sh stop   # 两端停止\nbash install-docker.sh start\nbash install-docker.sh down   # 两端移除容器，保留数据\n```\n\n后端备份不等于完整前端站点备份，.env、自定义静态资源和外层 TLS 配置应另外保存。Docker 不运行 systemd 证书续期 timer，仍需网页重新签发或宿主机续期流程；自动端口不替你更新安全组或外层反代。\n\n## Docker 安装速度与首次构建\n\n保留 0.2.5 main 的构建输入指纹缓存。运行文件相同且已有标记镜像时可复用；密码、节点、.env 和 README 不参与镜像指纹，首次仍需依赖和核心下载，不提供预构建项目镜像。前端首次还需拉取 Nginx 镜像。\n\n需要主动刷新基础镜像与依赖安全更新时（较慢）：\n\n```bash\nMIKU_DOCKER_REFRESH=1 bash install-docker.sh update\n```\n\n## 常见问题\n\n| 情况 | 检查 |\n| --- | --- |\n| 根目录 404 | 使用 frontend info 的完整随机路径入口 |\n| 登录 403 | 浏览器源与 MIKU_FRONTEND_ORIGIN 是否一致，别把路径填进 Origin |\n| 登录后 API 502\u002F504 | 实际后端地址、路径、Host\u002FTLS、跨机防火墙；同步后重启前端 |\n| 后端不是 8899 | 默认只是优先值，冲突自动避让，以 backend info 为准 |\n| 端口改后旧入口失效 | 重新获取实际地址；后端改配置后执行 frontend restart |\n| Nginx 无权读资源 | 使用新版 staging \u002F 启动器整理公开资源权限，不要把后端私钥整体改为公开 |\n| 资源清单校验失败 | 是否漏文件；有意修改后 refresh-manifest，不要关闭校验 |\n| 网页主程序更新返回 409 | Docker 应用通过宿主部署脚本 update，不在运行容器里替换二进制 |\n| 停前端后节点是否断？ | 前端 stop\u002Fdown 不主动停止后端；顶层 stop\u002Fdown 处理两端 |\n\n## 构建与验证\n\n源码构建需要 Go 1.26+。原生依赖与固定核心见 [CORE_ASSETS.json](CORE_ASSETS.json)。发布要求 Go race\u002Fvet、Python 维护\u002F端口\u002F前端回归、真实 Nginx 代理、两种页面 DOM、双架构源码构建、Docker 端口冲突\u002F登录\u002F持久化，以及所有附件和资源摘要验证通过。\n\nWindows 本地静态检查不等于 Linux 容器、真实 VPN Gate 隧道或证书签发验收。完整细节见 [前后端分离指南](docs\u002FFRONTEND.md)、[Docker 指南](docs\u002FDOCKER.md)、[连接策略](docs\u002FCONNECTION_POLICY.md)、[变更记录](CHANGELOG.md) 与 [验证记录](docs\u002FVALIDATION.md)。\n\n国旗许可证见 [FLAG_ICONS_LICENSE](FLAG_ICONS_LICENSE)，插画与字标见 [ARTWORK.md](ARTWORK.md)。项目不代表与角色权利人存在官方合作或背书。\n\n## v0.2.6 变化\n\n- Docker 默认两个独立 Compose 项目：非特权 Nginx 静态前端 + Go 后端。浏览器通过前端同源访问登录、API 和订阅，不是开放任意跨域后台接口。\n- 后端负责认证、VPN、入口、节点与数据；前端仅提供静态文件和代理，重启 \u002F 停止前端不会重启后端或节点。\n- 后端优先 8899、前端优先 8900，冲突自动避让，实际端口持久化；已健康运行的前端重复启动不会被自己的端口占用逼走。\n- 原生和仅后端模式继续支持内嵌页面。保留镜像构建指纹缓存、显式基础镜像刷新、quick\u002Fsub 和 v0.2.4 连接恢复策略。\n- 新增前端专用包，支持前端放另一台服务器；主程序和兼容助手从源码重建为 0.2.6，不复用输入包中的旧二进制。\n",2,"2026-10-31 04:26:27","CREATED_QUERY"]