nginx-proxy-manager 完整安装指南：Docker Compose 部署与 SQLite / MySQL / Postgres 多数据库配置
【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager
本指南以官方 完整安装文档 为主体，系统讲解 nginx-proxy-manager 在 Docker 环境下的完整部署流程：从最小化的docker-compose.yml起步，再到接入 MySQL/MariaDB、Postgres 外部数据库的完整配置，同时覆盖 ARM 设备部署注意事项与首次启动的内部机制。读完本文，你将能独立完成 nginx-proxy-manager 的生产级部署，理解各环境变量在源码层面的真实作用，并能根据自身场景选择合适的数据存储方案。
一、运行应用：最小化 Docker Compose 部署
nginx-proxy-manager 以预构建 Docker 镜像的形式发布，只需一个docker-compose.yml文件即可启动完整的前后端服务。
首先创建docker-compose.yml文件：
services: app: image: 'jc21/nginx-proxy-manager:{{VERSION}}' restart: unless-stopped ports: # These ports are in format <host-port>:<container-port> - '80:80' # Public HTTP Port - '443:443' # Public HTTPS Port - '81:81' # Admin Web Port # Add any other Stream port you want to expose # - '21:21' # FTP environment: TZ: "Australia/Brisbane" # Uncomment this if you want to change the location of # the SQLite DB file within the container # DB_SQLITE_FILE: "/data/database.sqlite" # Uncomment this if IPv6 is not enabled on your host # DISABLE_IPV6: 'true' volumes: - ./data:/data - ./letsencrypt:/etc/letsencrypt然后执行：
docker compose up -d端口与存储设计说明
80:80（HTTP 端口）：对外提供 HTTP 反向代理服务的入口，转发到你的代理主机（Proxy Hosts）。443:443（HTTPS 端口）：对外提供 HTTPS 反向代理服务的入口，用于 SSL 终止。81:81（管理端口）：Web 管理界面端口，容器内 Nginx 通过该端口对外提供前端静态资源与/api反向代理（见 production.conf.template）。镜像本身通过EXPOSE 80 81 443声明这三个端口（见 Dockerfile）。- 流端口（Stream）：如需暴露 TCP/UDP 流（例如 FTP 的
21端口），在ports中追加对应的<host-port>:<container-port>映射即可。 ./data:/data：数据卷，用于存放 SQLite 数据库文件、keys.json（JWT 密钥对）等运行时数据。Dockerfile 中以VOLUME ["/data"]显式声明（见 Dockerfile）。./letsencrypt:/etc/letsencrypt：证书卷，用于持久化 Let's Encrypt 签发的证书及 DNS 插件凭据。
二、数据库选择：三种后端与配置优先级
nginx-proxy-manager 默认使用 SQLite（零外部依赖），也支持接入 MySQL/MariaDB 与 Postgres。从源码 backend/lib/config.js 可以看出其配置读取优先级为：
- 配置文件优先（
config/default.json等，已不推荐）：若配置文件存在且含database字段，直接使用文件配置。 - 环境变量其次：依次检测
DB_MYSQL_*→DB_POSTGRES_*→ 兜底的DB_SQLITE_FILE。
这意味着：只要设置了DB_MYSQL_HOST、DB_MYSQL_USER、DB_MYSQL_NAME三个变量，即判定为 MySQL 模式；同理 Postgres 需要DB_POSTGRES_HOST、DB_POSTGRES_USER、DB_POSTGRES_NAME三者齐全；否则回落到 SQLite。Knex 层的客户端映射关系见 backend/db.js：MySQL 使用mysql2驱动、Postgres 使用pg驱动、SQLite 使用better-sqlite3（通过knex-native引擎透传原始 knex 配置）。
2.1 使用 MySQL / MariaDB 数据库
如果选择 MySQL 方案，你需要自行提供数据库服务。最方便的做法是用另一个 Docker 容器承载数据库，并把它作为同一 stack 的一部分串联起来。以下是使用 MariaDB 容器时的完整docker-compose.yml示例：
services: app: image: 'jc21/nginx-proxy-manager:{{VERSION}}' restart: unless-stopped ports: # These ports are in format <host-port>:<container-port> - '80:80' # Public HTTP Port - '443:443' # Public HTTPS Port - '81:81' # Admin Web Port # Add any other Stream port you want to expose # - '21:21' # FTP environment: TZ: "Australia/Brisbane" # Mysql/Maria connection parameters: DB_MYSQL_HOST: "db" DB_MYSQL_PORT: 3306 DB_MYSQL_USER: "npm" DB_MYSQL_PASSWORD: "npm" DB_MYSQL_NAME: "npm" # Optional SSL (see section below) # DB_MYSQL_SSL: 'true' # DB_MYSQL_SSL_REJECT_UNAUTHORIZED: 'true' # DB_MYSQL_SSL_VERIFY_IDENTITY: 'true' # Uncomment this if IPv6 is not enabled on your host # DISABLE_IPV6: 'true' volumes: - ./data:/data - ./letsencrypt:/etc/letsencrypt depends_on: - db db: image: 'linuxserver/mariadb' restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: 'npm' MYSQL_DATABASE: 'npm' MYSQL_USER: 'npm' MYSQL_PASSWORD: 'npm' TZ: 'Australia/Brisbane' volumes: - ./mariadb:/config::: warning 请注意，DB_MYSQL_*环境变量的优先级高于DB_SQLITE_*变量。只要你保留了 MySQL 相关的环境变量，就无法再使用 SQLite——即便同时设置了DB_SQLITE_FILE也会被忽略。这一行为与源码中的判定顺序完全一致（backend/lib/config.js 先检测 MySQL 变量组，再检测 Postgres，最后才回退 SQLite）。 :::
DB_MYSQL_PORT未显式设置时默认为3306，与示例中的取值对应。仓库默认的开发配置 backend/config/default.json 也展示了同样的 MySQL 参数结构（engine 为mysql2）。
2.2 可选：MySQL / MariaDB 连接启用 SSL/TLS
可以通过以下环境变量为 MySQL/MariaDB 连接启用 TLS：
DB_MYSQL_SSL：设为true时启用 SSL；未设置或为false时禁用（保持旧版默认行为）。DB_MYSQL_SSL_REJECT_UNAUTHORIZED：（默认true）校验服务器证书链。设为false可允许自签名证书 / 未知 CA。DB_MYSQL_SSL_VERIFY_IDENTITY：（默认true）执行主机名 / 身份校验。
这三个变量的默认值语义在源码 backend/lib/config.js 中有精确实现：DB_MYSQL_SSL_REJECT_UNAUTHORIZED与DB_MYSQL_SSL_VERIFY_IDENTITY在环境变量未定义时均默认为true；当DB_MYSQL_SSL为真时，二者会被合并为{ rejectUnauthorized, verifyIdentity }传入 knex 的ssl连接选项（见 backend/db.js）。
使用自签名证书启用 SSL 的示例（官方明确提示：不推荐用于生产环境）：
environment: DB_MYSQL_SSL: 'true' DB_MYSQL_SSL_REJECT_UNAUTHORIZED: 'false' DB_MYSQL_SSL_VERIFY_IDENTITY: 'false'2.3 使用 Postgres 数据库
Postgres 的接入方式与 MySQL 类似，同样推荐用独立的 Postgres 容器作为 stack 的一部分：
services: app: image: 'jc21/nginx-proxy-manager:{{VERSION}}' restart: unless-stopped ports: # These ports are in format <host-port>:<container-port> - '80:80' # Public HTTP Port - '443:443' # Public HTTPS Port - '81:81' # Admin Web Port # Add any other Stream port you want to expose # - '21:21' # FTP environment: TZ: "Australia/Brisbane" # Postgres parameters: DB_POSTGRES_HOST: 'db' DB_POSTGRES_PORT: '5432' DB_POSTGRES_USER: 'npm' DB_POSTGRES_PASSWORD: 'npmpass' DB_POSTGRES_NAME: 'npm' # Uncomment this if IPv6 is not enabled on your host # DISABLE_IPV6: 'true' volumes: - ./data:/data - ./letsencrypt:/etc/letsencrypt depends_on: - db db: image: postgres:17 environment: POSTGRES_USER: 'npm' POSTGRES_PASSWORD: 'npmpass' POSTGRES_DB: 'npm' volumes: - ./postgres_data:/var/lib/postgresql/dataDB_POSTGRES_PORT未显式设置时默认5432（见 backend/lib/config.js）。仓库自身的开发环境同样使用postgres:17镜像，参见 docker-compose.dev.yml 中的db-postgres服务。
::: warning Postgres 不支持自定义 schema，因此将固定使用publicschema。请勿在DB_POSTGRES_NAME或连接串中指定其他 schema。 :::
三、在 Raspberry Pi / ARM 设备上运行
Docker 镜像支持以下架构：
- amd64
- arm64
镜像本身是一个包含多架构构建的 manifest 列表，因此你无需做任何特殊处理——直接按照上述通用步骤运行即可，Docker 会自动拉取匹配你设备架构的镜像层。
::: warningarmv7架构在 2.14+ 版本中不再受支持，原因是 Node.js 已停止对 armhf（32 位 ARM）的支持。如果你的设备属于 armv7，请改用2.13.7镜像标签。 :::
如果你希望在 Raspbian 上运行 nginx-proxy-manager，需要先在系统上安装好 Docker 与 Docker Compose 环境，然后再执行本指南第一节中的部署步骤。
四、首次启动（Initial Run）会发生什么
应用第一次启动后，后端进程会自动完成以下初始化工作（对应源码 backend/setup.js 的初始化链，该初始化通过 s6-overlay 的prepare阶段触发）：
- 生成 JWT 密钥对并保存到 data 目录：源码 backend/lib/config.js 中的
getKeys()/generateKeys()会在/data/keys.json不存在时，用 NodeRSA 生成 2048 位 RSA 密钥对并以0o600权限写入该文件；此后所有接口的 JWT 签发与校验（getPrivateKey/getPublicKey）都依赖这对密钥。 - 初始化数据库表结构：Knex 迁移脚本（位于 backend/migrations）会在首次启动时建表并记录迁移版本，覆盖代理主机、流、证书、访问列表、用户、设置、审计日志等全部数据模型。
- 创建默认管理员用户：若数据库中不存在任何活跃用户，则会进入初始化流程。若设置了
INITIAL_ADMIN_EMAIL与INITIAL_ADMIN_PASSWORD两个环境变量，将自动创建一个Administrator用户（角色为admin，拥有所有资源的manage权限）；否则由前端引导用户通过首次设置向导创建管理员（见 backend/setup.js）。 - 同时会写入默认设置（如
default-site）并启动日志轮转定时任务（每两天执行一次logrotate）。
整个过程在你的机器上可能需要一两分钟，取决于硬件性能与密钥生成的熵池情况。因此首次部署后请耐心等待管理界面（http://127.0.0.1:81）可用，再开始登录。
五、进阶环境变量与源码佐证
除文档明确列出的变量外，仓库中还有若干与部署强相关的环境变量，可从源码中确认其行为：
| 环境变量 | 默认值 | 作用 | 源码位置 |
|---|---|---|---|
DB_SQLITE_FILE | /data/database.sqlite | 指定 SQLite 数据库文件在容器内的路径 | backend/lib/config.js |
DB_MYSQL_PORT | 3306 | MySQL 连接端口 | backend/lib/config.js |
DB_POSTGRES_PORT | 5432 | Postgres 连接端口 | backend/lib/config.js |
NPM_ADMIN_PORT | 81 | 管理界面监听端口（仅接受数字，非法时回退 81） | 45-admin-port.sh |
DISABLE_IPV6 | 未设置 | 设为true时禁用 Nginx 配置中的 IPv6 监听 | 50-ipv6.sh、backend/internal/nginx.js |
TZ | 无 | 容器时区，建议设为你的本地时区（如Asia/Shanghai） | 各 compose 示例 |
INITIAL_ADMIN_EMAIL/INITIAL_ADMIN_PASSWORD | 无 | 首次启动时自动创建管理员（自动化部署场景） | backend/setup.js |
另外，LE_STAGING（使用 Let's Encrypt 暂存环境）与LE_SERVER（自定义 ACME 服务器地址）等证书签发相关变量也由 backend/lib/config.js 支持，适合测试与内网 CA 场景；仓库的 docker-compose.dev.yml 即为带LE_STAGING、LE_SERVER的开发环境示例。
六、常见部署要点小结
- 端口规划：
80/443必须可被公网（或内网目标）访问，81仅用于管理界面，可按需绑定到内网或加防火墙限制。 - 数据持久化：务必同时挂载
./data:/data与./letsencrypt:/etc/letsencrypt，否则重启容器会丢失数据库、密钥与已签发证书。 - 数据库升级路径：SQLite 是零依赖的默认选择，适合单机小规模场景；需要多实例共享状态或已有 MySQL/Postgres 基础设施时，再选择对应的
DB_MYSQL_*或DB_POSTGRES_*方案，注意DB_MYSQL_*会覆盖 SQLite 配置。 - 升级注意事项：镜像 tag 使用具体版本（
{{VERSION}}在构建文档时会被替换为实际版本号）可避免意外升级；armv7 用户请停留在2.13.7。 - 首次启动等待：初始化（密钥生成、迁移建表）可能耗时数分钟，属正常现象，可通过观察容器日志确认进度。
至此，你已完成 nginx-proxy-manager 从零到生产可用的完整部署。接下来即可通过http://<主机IP>:81登录管理界面，创建你的第一个代理主机（Proxy Host），并配置 Let's Encrypt 免费证书；更深入的功能（代理主机、证书、访问列表、流与用户权限等）可继续查阅仓库 README.md 与 docs/src 下的对应文档。
【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
