NPSNPS
首页
  • 安装与部署
  • 快速开始
  • 运行命令速查
  • 隧道模式
  • 使用示例
  • 使用说明
  • 配置文件
  • 增强功能
  • Docker 部署
  • 参数与安全速查
  • 使用说明
  • 增强功能
  • 配置与启动
  • 配置文件参考
  • 更新与远程升级
  • SDK
  • 功能概览
  • 域名代理与路由
  • 平台域名与证书诊断
  • 访问控制与配额
  • 运行说明
  • 配置示例
  • 对外 API v1
  • API 鉴权与兼容
  • 历史 Web API
  • 用户体系
  • FAQ
  • 升级迁移
  • 功能与兼容矩阵
  • 本项目更新日志
  • 上游更新日志
GitHub
首页
  • 安装与部署
  • 快速开始
  • 运行命令速查
  • 隧道模式
  • 使用示例
  • 使用说明
  • 配置文件
  • 增强功能
  • Docker 部署
  • 参数与安全速查
  • 使用说明
  • 增强功能
  • 配置与启动
  • 配置文件参考
  • 更新与远程升级
  • SDK
  • 功能概览
  • 域名代理与路由
  • 平台域名与证书诊断
  • 访问控制与配额
  • 运行说明
  • 配置示例
  • 对外 API v1
  • API 鉴权与兼容
  • 历史 Web API
  • 用户体系
  • FAQ
  • 升级迁移
  • 功能与兼容矩阵
  • 本项目更新日志
  • 上游更新日志
GitHub
  • 文档首页
  • 快速上手

    • 安装与部署
    • 快速开始
    • 运行命令速查
    • 完整部署参考
    • 隧道模式
    • 使用示例
  • 服务端

    • 服务端使用
    • 使用说明页面配置
    • 配置文件参考
    • 服务端增强功能
    • 服务端介绍
    • 部署安全与参数速查
    • Docker 部署
    • 宝塔面板部署
  • 客户端

    • 客户端使用
    • 客户端增强功能
    • NPC SDK
    • 客户端配置与启动
    • 配置文件参考
    • NPC Docker 部署
    • 飞牛 fnOS 原生包
    • NPC GUI 客户端
    • 客户端更新与远程升级
  • 扩展功能

    • 功能概览
    • 域名代理与路由
    • 平台域名与证书诊断
    • 访问控制与配额
    • 运行说明
    • 对外 API v1
    • API 鉴权与兼容
    • 历史 Web API
    • 使用示例
  • 项目与社区

    • 用户体系
    • 系统架构
    • 升级迁移
    • 功能与兼容矩阵
    • 构建发布
    • 本项目更新日志
    • 上游更新日志
    • FAQ
    • 贡献
    • 交流
    • 捐助
    • 致谢

构建发布

本项目包含服务端 nps、命令行客户端 npc、GUI 客户端、Docker 镜像和飞牛 fnOS NPC 客户端包。

环境要求

  • Go 1.26.0(以根目录 go.mod 和 cmd/npc/npc-gui/go.mod 为准)
  • Node.js 20+
  • Yarn 1.22.22(GUI 前端)
  • Wails v3.0.0-beta.12(GUI 客户端,需与 cmd/npc/npc-gui/go.mod 一致)
  • Docker Buildx(Docker 多架构镜像)
  • Python 3(飞牛 FPK 构建脚本)

本地构建

服务端:

go build ./cmd/nps

客户端:

go build ./cmd/npc

Makefile:

make build
make test
make lint
make ci

交叉编译

Linux amd64 服务端:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -ldflags "-s -w" ./cmd/nps

Windows amd64 客户端:

CGO_ENABLED=0 GOOS=windows GOARCH=amd64 \
  go build -ldflags "-s -w" ./cmd/npc

GUI 客户端

前端依赖:

cd cmd/npc/npc-gui/frontend
corepack enable
corepack prepare yarn@1.22.22 --activate
yarn install --frozen-lockfile
yarn build

Wails 3 构建(Windows/macOS):

cd cmd/npc/npc-gui
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-beta.12
wails3 build --tags npcgui

wails.json 已配置为使用 Yarn。不要混用 npm 生成 package-lock.json。

Linux GUI 使用 Wails 3 的 GTK4/WebKitGTK 6 默认构建链,需要安装以下开发依赖:

sudo apt-get install build-essential libgtk-4-dev libwebkitgtk-6.0-dev \
  libsoup-3.0-dev libjavascriptcoregtk-6.0-dev \
  libayatana-appindicator3-dev librsvg2-dev patchelf pkg-config
cd cmd/npc/npc-gui
GOOS=linux GOARCH=amd64 wails3 build --tags npcgui

Linux GUI 构建需要 CGO_ENABLED=1。上表对应的是当前发布工作流使用的 GTK4/WebKitGTK 6 组合;不要同时安装或传入旧版 GTK3/WebKitGTK 4.1 构建参数。

Docker 镜像

服务端:

docker build -f Dockerfile.nps -t nps .

客户端:

docker build -f Dockerfile.npc -t npc .

GitHub Actions 发布

.github/workflows/release.yml 包含:

  • 跨平台 nps / npc 二进制打包
  • config-examples.tar.gz 配置示例包(不含运行数据、证书和私钥)
  • Android APK 打包
  • Docker 多架构镜像构建与推送
  • NPC 飞牛 fnOS 原生 FPK(仅客户端;不含 NPS 服务端包)
  • Windows/macOS/Linux GUI 客户端打包
  • Release 附件上传

.github/workflows/ci.yml 在推送 master 或创建面向 master 的 Pull Request 时执行服务端/客户端构建、核心 Go 包测试,以及 GUI 前端的冻结依赖安装和构建,也可以手动触发。CI 只负责验证代码,不推送镜像、不创建 Release。文档站使用 docs/package-lock.json 与 npm ci 构建,确保 Pages 部署可复现;.github/workflows/docs.yml 只在推送 v* 正式标签时部署(另保留从标签手动重跑的入口)。

普通代码提交不会触发 Docker 发布。.github/workflows/docker.yml 仅保留从已有 v* 标签手动重跑的兜底入口,正式镜像由 Release 工作流统一推送版本号和 latest,避免一次发版生成两套来源不同的镜像标签。

推送与源码版本严格一致的标签(例如源码为 1.1.47 时推送 v1.1.47)才会运行 Release 工作流并创建 GitHub Release。正式标签必须指向当前 master 提交,工作流会在构建前校验版本元数据和核心 Go 测试;CLI/GUI 自动更新和服务端下发的 NPC 在线升级仍只读取 GitHub 上经过完整校验的最新正式 Release,并按 lib/version.VERSION 与 Release tag 比较,不依赖 Docker 标签。所有平台产物完成后一次性上传 CLI、Android、GUI 和 checksums.txt;Release 的 Docker 构建同时推送版本号镜像(如 1.1.47)和 latest。因此正式发版只需:先把准备好的代码推送到 master,确认版本号后创建并推送对应的 vX.Y.Z 标签。也可以在 Actions 页面手动执行 Release 的 workflow_dispatch,但 release_tag 必须与 lib/version.VERSION 对应(例如 v1.1.47),并且该标签已推送且指向当前 master。Docker 镜像发布需要配置 DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN secrets。

更新器只按 lib/version.VERSION 与 GitHub 最新正式 Release 比较,不会从 Docker Hub 的 latest 推断版本;因此只有正式标签完成 Release 后,latest 才会指向该版本。

飞牛 FPK

FPK 只打包 NPC 客户端,使用官方 fnpack 1.2.3 和固定 SHA-256 校验。构建脚本从 conf/npc.conf 释放完整模板,再把对应架构的静态 npc 放入 FPK;模板不会覆盖设备 etc 目录中的现有配置。

python3 tools/build-fnos.py --fnpack /path/to/fnpack-1.2.3-linux-amd64 --arch amd64
python3 tools/build-fnos.py --fnpack /path/to/fnpack-1.2.3-linux-amd64 --arch arm64

产物在 dist/fnos/,包含 FPK 和外层 SHA-256。流水线只发布这两个 NPC 包;飞牛和 Docker 均通过应用中心或镜像更新,不接受 NPS 服务端下发远程自更新。没有飞牛真机时,CI 只能验证包结构和脚本,不能替代安装、升级和原生向导验收。

GUI 构建由 Wails 3 调用 wails.json 中配置的 Yarn 前端流程:

wails3 build --tags npcgui

注意:package.json 和 wails.json 必须是无 BOM 的 UTF-8,否则 Yarn 或 Wails 在 CI 中可能报 Invalid package.json 或 JSON 解析失败。

在 GitHub 上编辑此页
最后更新: 2026/11/16 23:39
Prev
功能与兼容矩阵
Next
本项目更新日志