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
    • 贡献
    • 交流
    • 捐助
    • 致谢

NPC Docker 部署

NPC 是主动连接 NPS 的客户端容器。普通 TCP、KCP、TLS Bridge 隧道不需要给 NPC 映射公网端口;容器只需要能够访问 NPS 的 Bridge 地址,以及能够访问 npc.conf 中填写的内网目标。

镜像地址:wushuo98/npc。本文同时介绍命令行模式、配置文件模式和 Docker Compose 模式。

选择启动方式

方式适用场景配置来源
命令行模式只连接一个或少量客户端,规则由 Web 面板管理-server、-vkey 等参数
配置文件模式批量部署、静态规则、健康检查、端口范围映射挂载的 npc.conf
Compose 模式需要自动重启、固定挂载和可重复部署docker-compose.yml + npc.conf

常规部署推荐使用命令行模式,客户端、隧道和 Host 规则统一在 NPS Web 面板维护。只有需要把规则纳入配置管理,或使用配置文件专属能力时,才使用 npc.conf。

最小启动:命令行模式

先在 NPS Web 面板创建客户端,复制该客户端的 VerifyKey,然后启动容器:

docker pull wushuo98/npc:1.1.43

docker run -d \
  --name npc \
  --restart unless-stopped \
  wushuo98/npc:1.1.43 \
  -server=<NPS地址>:8024 \
  -vkey=<VerifyKey>

使用 TLS Bridge 时,连接服务端的 TLS Bridge 端口并启用 TLS:

docker run -d \
  --name npc \
  --restart unless-stopped \
  wushuo98/npc:1.1.43 \
  -server=<NPS地址>:8025 \
  -vkey=<VerifyKey> \
  -tls_enable=true

多个客户端可以在同一个进程中用英文逗号分隔:

docker run -d \
  --name npc \
  --restart unless-stopped \
  wushuo98/npc:1.1.43 \
  -server=<NPS地址>:8024 \
  -vkey=<VerifyKey1>,<VerifyKey2>

latest 始终指向最近一次正式 Release,不会跟随普通 master 提交更新;生产环境建议固定使用版本号,升级时明确执行 docker pull 和容器重建。

使用 npc.conf

NPC 镜像不会自动生成配置文件。仓库中的 conf/npc.conf 是参考模板,需要复制到宿主机后再修改。

1. 准备配置目录

mkdir -p /opt/npc/conf
cp conf/npc.conf /opt/npc/conf/npc.conf

至少修改 [common] 中的服务端地址和验证密钥:

[common]
server_addr=nps.example.com:8024
conn_type=tcp
vkey=replace-with-verify-key
auto_reconnection=true

完整字段和所有规则示例见 NPC 配置文件参考。

2. 挂载配置并启动

docker run -d \
  --name npc \
  --restart unless-stopped \
  -v /opt/npc/conf:/conf:ro \
  wushuo98/npc:1.1.43 \
  -config=/conf/npc.conf

配置文件模式下,规则节中的 target_addr 是从 NPC 容器网络命名空间访问的地址。例如:

[tcp_ssh]
mode=tcp
target_addr=192.168.14.20:22
server_port=10022

不要把容器内的 127.0.0.1 误认为宿主机地址;它只指向 NPC 容器自身。

Docker Compose

创建 /opt/npc/docker-compose.yml:

services:
  npc:
    image: wushuo98/npc:1.1.43
    container_name: npc
    restart: unless-stopped
    volumes:
      - ./conf:/conf:ro
    command: ["-config=/conf/npc.conf"]

准备 /opt/npc/conf/npc.conf 后启动:

cd /opt/npc
docker compose up -d
docker compose logs -f npc

NPC 只发起出站连接时不需要 ports。如果配置了 P2P/Secret 本地访问端,或其他需要在宿主机监听的本地端口,再显式增加端口映射。

容器网络与内网目标

Linux:目标服务在宿主机上

如果 target_addr 是宿主机上的 127.0.0.1:端口,可使用 host 网络,让 NPC 和宿主机共享网络命名空间:

docker run -d \
  --name npc \
  --restart unless-stopped \
  --network host \
  -v /opt/npc/conf:/conf:ro \
  wushuo98/npc:1.1.43 \
  -config=/conf/npc.conf

Compose 写法:

services:
  npc:
    image: wushuo98/npc:1.1.43
    container_name: npc
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./conf:/conf:ro
    command: ["-config=/conf/npc.conf"]

使用 network_mode: host 时不要再配置 ports。该模式主要适用于 Linux;Windows/macOS Docker Desktop 应使用宿主机可达地址(例如 Docker 提供的宿主机网关地址),不要直接照搬 127.0.0.1。

普通 Bridge 网络

如果目标服务在局域网其他设备上,直接填写 NPC 容器可以访问的局域网地址即可,例如 192.168.14.20:8080。同时确认:

  • NPC 容器到目标地址的路由和防火墙允许访问。
  • NPS 地址是 NPC 容器可以访问的公网或内网地址。
  • 只给 NPS 放行必要的 Bridge 端口(通常为 8024 或 8025)。

TLS、CA 和其他挂载文件

自签名证书或自定义 CA 需要把证书文件挂载进容器,并在 npc.conf 中使用容器内的绝对路径:

services:
  npc:
    image: wushuo98/npc:1.1.43
    restart: unless-stopped
    volumes:
      - ./conf:/conf:ro
      - ./certs:/certs:ro
    command: ["-config=/conf/npc.conf"]
[common]
server_addr=nps.example.com:8025
vkey=replace-with-verify-key
tls_enable=true
tls_ca_file=/certs/nps-ca.pem
tls_server_name=nps.example.com

如果使用 SOCKS5 多账号认证或文件访问,也要将对应文件/目录挂载到容器内,并在配置中使用容器内路径:

volumes:
  - ./conf:/conf:ro
  - ./share:/srv/share:ro
[socks_outbound]
mode=socks5
server_port=19009
multi_account=/conf/multi_account.conf

[file_share]
mode=file
server_port=19008
local_path=/srv/share

日志、状态与排查

NPC 镜像基于 scratch,容器内没有 sh、curl 等诊断命令。请使用 Docker 日志和宿主机工具排查:

docker ps --filter name=npc
docker logs --tail=100 npc
docker logs -f npc
docker inspect npc --format '{{.State.Status}} {{.State.ExitCode}}'

常见问题:

现象优先检查
容器不断重启docker logs npc,重点看配置文件路径、地址和验证密钥
connection refusedNPS 的 bridge_port/tls_bridge_port、安全组、防火墙和 DNS
验证失败Web 面板中的 VerifyKey 是否属于当前客户端,是否误用了旧密钥
隧道已连接但访问失败target_addr 是否从容器网络可达,是否把宿主机服务误写成 127.0.0.1
TLS 握手失败tls_enable、端口、CA 路径、SNI 和证书指纹是否匹配
修改配置不生效配置以只读挂载后,需要重建或重启容器

修改挂载的配置后执行:

docker compose up -d --force-recreate

升级与回滚

NPC 容器明确不支持在内部覆盖二进制自更新。新版客户端会把此限制上报给 NPS,面板显示需更新镜像;请勿通过给容器加写权限来绕过。其他运行方式及 旧客户端迁移见客户端更新与远程升级。

使用 Compose 时,先备份配置,再拉取目标版本并重建:

cd /opt/npc
cp -a conf conf.bak.$(date +%Y%m%d%H%M%S)
docker compose pull
docker compose up -d

回滚时把 image 改回上一个版本号,例如 wushuo98/npc:1.1.26,再执行 docker compose up -d。NPC 容器升级不会修改挂载的 npc.conf。

相关文档

  • 客户端配置与启动
  • NPC 配置文件参考
  • 客户端使用
  • 服务端 Docker 部署
在 GitHub 上编辑此页
最后更新: 2026/11/9 21:01
Prev
配置文件参考
Next
飞牛 fnOS 原生包