nginx-proxy-manager-zh 完整指南从零搭好你的自托管服务反向代理网关【免费下载链接】nginx-proxy-manager-zh基于nginx-proxy-manager翻译的中文版本项目地址: https://gitcode.com/gh_mirrors/ng/nginx-proxy-manager-zh服务器上自托管服务多了Jitsi、Gitea、Grafana 的域名和证书各管各的改一行 Nginx 配置就头大。nginx-proxy-manager-zh 是一款中文界面的 Nginx 反向代理管理工具代理规则、HTTPS 证书自动签发与续签、IP 黑白名单全在浏览器表单里点完不用手写 conf。本文从部署讲到排障一次跑通。 工具定位给自托管服务装一个浏览器里的网关一句话它把 Nginx 的反向代理能力包进一个 Docker 容器里你在网页表单里点什么它就生成对应的 conf 并热加载顺便把 Lets Encrypt 证书的签发、续签全托管掉。这个中文版本基于官方 nginx-proxy-manager 构建只替换了前端界面所以功能与英文版完全一致菜单、提示、文档全是中文。它适合谁自托管玩家 / 家庭实验室一堆容器服务想统一挂域名、上 HTTPS但不想维护一堆 conf 文件小团队运维需要给内网服务加 IP 白名单、基本认证这类访问控制且要留审计痕迹对 Nginx 半生不熟的人常用场景WebSocket、强制 HTTPS、HSTS、自定义 location都有勾选框。选型一句话对比你的情况比较合适的选择两三个服务愿意写配置直接手写 Nginx 或 Caddy最灵活几十个服务、要界面、要中文nginx-proxy-manager-zh服务已经全部跑在 K8s 上直接用 ingress-nginx 等 Ingress 方案 一图看懂一次请求是怎么流转的这个容器里其实跑着两套系统面向公网的 Nginx负责代理 80/443 流量和面向你的管理端81 端口的 Web UI Express API 数据库。【业务流量】 浏览器 ──80/443──▶ Nginx ──按域名匹配──▶ 内网服务Jitsi / Gitea / Grafana … ▲ │ 由模板渲染出的 conf 驱动 【管理流量】 管理界面(81) ──▶ Express API ──▶ 数据库(SQLite 默认) 保存时模板渲染 → nginx -t 校验 → 通过才 reload注意最下面那行每次你在界面点保存都会走模板渲染 →nginx -t语法校验 → reload的流程校验不通过就自动回滚并把这个主机在界面上标为离线而不是让一台错误配置把你整站打挂。这是它比手写 conf 安心得多的核心原因。️ 快速上手3 步跑起中文镜像第 1 步准备环境装好 Docker 和 Docker Compose然后确认宿主机80、443、81 三个端口空闲81 是管理界面若被占用可改成8181:81。镜像支持 amd64 / arm64 / armv7树莓派可以直接跑。国内网络拉取chishin/nginx-proxy-manager-zh镜像慢的话先在 Docker 配置里加镜像加速器再拉别反复重试。第 2 步写 compose 文件services: app: image: chishin/nginx-proxy-manager-zh:release # 中文界面镜像 restart: unless-stopped ports: - 80:80 # 公网 HTTPLets Encrypt 验证也要用它 - 443:443 # 公网 HTTPS - 81:81 # 管理界面只建议对可信网络开放 volumes: - ./data:/data # 数据库、JWT 密钥务必持久化 - ./letsencrypt:/etc/letsencrypt # 证书存放重建容器不丢两个数据卷是唯一的家当备份好./data和./letsencrypt换机器迁移就靠它们。第 3 步启动并完成首次登录docker compose up -d # 首次初始化要几分钟生成密钥、建表、创建管理员 docker compose ps # 确认容器 healthy浏览器访问http://服务器IP:81用默认账号登录后会强制要求改邮箱和密码别跳过——这个邮箱用来收证书到期提醒Email: adminexample.com Password: changeme如果想跳过首次改密流程可以在 compose 里预设INITIAL_ADMIN_EMAIL和INITIAL_ADMIN_PASSWORD两个环境变量。⚙️ 能力拆解四个干活的模块 能力一 | 代理主机一个表单暴露一个内网服务能做什么把域名 → 内网容器:端口映射成一条反向代理规则勾选框覆盖 WebSocket、缓存、已知漏洞拦截还能加自定义 location比如把/api单独转发给另一个后端、并在高级配置里注入原生 Nginx 指令。什么时候用暴露任何 Web 服务时的默认选择。项目里还有三种伴生主机类型类型用途代理主机真正的反向代理重定向主机只做 301/302/308 跳转比如裸域跳www流主机直接转发 TCP/UDP 端口非 HTTP 流量停机主机让 Nginx 对某域名返回 503下线但不删配置注意点转发目标建议填容器名 / Docker 网络内的主机名而不是宿主机 IP否则容易绕出公网或直接 502。需要长连接的服务Jitsi、各类 WebSocket 应用记得勾选 WebSocket 支持。 能力二 | SSL 自动化HTTPS 证书自动签发与自动续签能做什么选 Lets Encrypt 作为证书来源两种方式——HTTP 验证靠 80 端口下发验证文件要求 80/443 公网可达和 DNS 服务商验证调 DNS API通配符证书必须用它。配套开关强制 SSLHTTP 301 跳 HTTPS、HTTP/2、HSTS。证书 90 天到期前会自动续签存进./letsencrypt数据卷。什么时候用任何有公网域名的服务默认全开。家庭实验室用 DDNS 公网 IP 时HTTP 验证即可想给*.home.lab一把通配证书就切 DNS 验证。注意点HTTP 验证失败九成是域名没解析到本机、或 80 端口没放通别先怀疑工具本身。 能力三 | 访问控制按 IP 和账号决定放行能做什么先建访问列表ACL再挂到具体主机上。ACL 有两种玩法按IP / CIDR 段做允许或拒绝按用户名 密码HTTP 基本认证做门禁。同一主机可以拒绝名单 允许名单叠加使用。什么时候用Grafana、Portainer、文件同步这类不该对整个公网开放的管理面板给团队服务加一道账号门禁。注意点如果目标应用自己也用基本认证登录它和 NPM 的认证会抢同一个Authorization头导致两边有一边登录不上——这类服务二选一优先用 IP 白名单。 能力四 | 高级配置与自定义模板表单不够用的出口能做什么每台主机有一个高级配置文本框直接注入原始 Nginx 片段——限流、proxy_*_timeout、额外响应头、Gzip 白名单都从这里进默认站点没匹配到任何主机的请求落到哪也可改。所有 conf 由backend/templates/目录下的 Liquid 模板渲染生成proxy_host.conf、stream.conf、_certificates.conf、_access.conf等读懂它们能帮你判断这个需求到底该用哪个表单选项。什么时候用表单勾不出来的需求才动它90% 的场景前面的勾选框就够。注意点不要手改容器里已生成的 conf 文件——它归 NPM 所有下一次保存就会重新渲染把你改的覆盖掉。改动一律放高级配置或深度定制时自行 fork 模板重新构建镜像。 落地案例家庭实验室一次接入 4 个服务场景一台带公网 IP 的家用服务器域名home.labDocker 里跑了 4 个服务目标是一个域名规划、一把证书、各配各的访问控制。子域名服务转发到附加配置app.home.labJitsi Meetjitsi:443强制 SSL WebSocketgit.home.labGiteagitea:3000访问列表仅团队成员账号grafana.home.labGrafanagrafana:3000访问列表仅允许家庭网段 CIDRmedia.home.labJellyfinjellyfin:8096强制 SSL操作路径一把证书在证书里用 DNS 服务商验证申请*.home.lab通配符HTTP 验证拿不到通配符批量建主机按上表逐台添加代理主机全部选用这把通配证书挂访问控制先建两个 ACL一个账号型、一个 CIDR 型分别挂到 Gitea 和 Grafana验证curl -I https://git.home.lab # 期望返回 200且证书 CN 匹配 *.home.lab主机多到不想点界面时十几台以上别硬点创建一个 API Token用脚本批量调用接口建主机体验会好得多——backend/routes/下的接口是全的。 排障手册先查这四处① 现象访问代理主机返回 502 / 连接被拒可能原因转发目标填错用了宿主机 IP 而非容器名、两边不在同一 Docker 网络、目标容器没起来。 处理动作docker compose ps确认目标容器状态确认 NPM 容器与目标容器已连入同一网络docker network ls在 NPM 容器内curl -I http://目标:端口验证连通性。② 现象Lets Encrypt 申请失败提示验证错误可能原因DNS 未解析到本机、80/443 端口未对公网开放、解析还没生效。 处理动作先用nslookup 域名确认 A 记录正确再检查路由器端口转发与防火墙换 DNS 服务商验证则检查 API 密钥权限。③ 现象给主机加了账号密码后目标应用反而登录不上可能原因NPM 基本认证与应用自身的认证共用Authorization请求头互相覆盖。 处理动作该服务改用 IP 白名单或去掉应用侧的基本认证。④ 现象用 DNSPod 做 DNS 验证时证书一直创建失败ARM 设备尤其常见可能原因certbot-dns-dnspod插件依赖的zope在 ARM 上安装失败没能打进镜像。 处理动作进容器手工补装后重试docker exec -it 容器名 bash pip install certbot-dns-dnspod pip install zope exit 下一步把日志接出去内置审计日志记录了谁在什么时候改了什么Nginx 的 access / error 日志可以配 Logstash/Loki 采集排障从翻容器升级成搜日志。API 自动化创建 API Token 后配合脚本做主机批量创建、证书状态巡检接入你自己的 CI/定时任务。平滑升级docker compose pull docker compose up -d即可换新版本中文镜像持续跟随官方版本更新数据库迁移自动完成。规模再上台阶服务全部进 K8s 后这部分可以迁移给 ingress-nginxNPM 留作边缘与非 K8s 服务的入口。现在就可以打开 81 端口把那个用IP:端口凑合了很久的服务加上去——五分钟后一个带域名和有效证书的地址就在等你了。【免费下载链接】nginx-proxy-manager-zh基于nginx-proxy-manager翻译的中文版本项目地址: https://gitcode.com/gh_mirrors/ng/nginx-proxy-manager-zh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考