部署方式

版本要求

版本 > 1.5.3 单体部署时，必须搭建好 PostgreSQL，SQLite 已弃用。

Docker 单容器（内置 PostgreSQL）

镜像内已集成 PostgreSQL，推荐此方式。

一键启动（极简配置，首次启动进入初始化向导）：

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -e PUID=1000 \
  -e PGID=1000 \
  -v ./docker_local/logs:/share/logs:ro \
  -v ./docker_local/nginxpulse_data:/app/var/nginxpulse_data \
  -v ./docker_local/pgdata:/app/var/pgdata \
  -v ./docker_local/configs:/app/configs \
  -v /etc/localtime:/etc/localtime:ro \
  magiccoders/nginxpulse:latest

PUID/PGID 需要替换为你本机所对应的正确值，此处的作用是用于应对目录权限不一致时引发的应用无法读取日志的情况。具体请移步下方的Docker 部署权限说明)

常用环境变量（容器内置 PG）：

POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB: PG 账号与库名
POSTGRES_PORT: PG 端口（默认 5432）
POSTGRES_LISTEN: PG 监听地址（默认 127.0.0.1）
POSTGRES_CONNECT_HOST: 应用连接 PG 的地址（默认 127.0.0.1）
DATA_DIR: 数据目录（默认 /app/var/nginxpulse_data）
PGDATA: PG 数据目录（默认 /app/var/pgdata）

如果你想外接自建 PG，可显式传入 DB_DSN，内置 PG 会被绕过。此时不会启动内置 PG，POSTGRES_* 参数会被忽略，/app/var/pgdata 也无需挂载。

Docker Compose

仓库根目录已提供 docker-compose.yml，可直接复制修改：

调整日志挂载路径。
若日志或数据目录权限不一致，可配置 PUID/PGID 对齐宿主机 UID/GID。
挂载 nginxpulse_data、configs 保持数据持久化；如使用内置 PG 再挂载 pgdata。
保持 /etc/localtime 只读挂载，以确保时区一致。
SELinux 系统（RHEL/CentOS/Fedora）可在 volume 后追加 :z 或 :Z 重新打标签。

一键启动（极简配置，首次启动进入初始化向导）：

docker compose -f docker-compose-simple.yml up -d

Docker 部署权限说明

镜像默认以非 root 用户（nginxpulse）运行。容器里能否读取日志、写入数据，取决于宿主机目录的权限。你在容器里用 cat 看到日志，通常是因为 docker exec 默认是 root，不代表应用用户有权限。

推荐做法：让容器内用户的 UID/GID 与宿主机日志/数据目录的属主一致。

步骤 1：查看宿主机目录的 UID/GID

ls -n /path/to/logs /path/to/nginxpulse_data /path/to/pgdata
# 或
stat -c '%u %g %n' /path/to/logs /path/to/nginxpulse_data /path/to/pgdata

步骤 2：启动容器时传入 PUID/PGID（与上面一致）

docker run ... \
  -e PUID=1000 \
  -e PGID=1000 \
  -v /path/to/logs:/var/log/nginx:ro \
  -v /path/to/nginxpulse_data:/app/var/nginxpulse_data:rw \
  -v /path/to/pgdata:/app/var/pgdata:rw \
  ...

步骤 3：确保目录对该 UID/GID 可读/可写

chown -R 1000:1000 /path/to/nginxpulse_data /path/to/pgdata
chmod -R u+rx /path/to/logs

如果你使用外部数据库（设置 DB_DSN），可以不挂载 pgdata。

SELinux 说明（RHEL/CentOS/Fedora 等）：

这些系统默认启用 SELinux，Docker 挂载目录可能因安全上下文导致“看得见但不可访问”。
解决办法是在 volume 后加 :z 或 :Z 重新打标签：
- :Z 让该目录仅供当前容器使用（更严格）。
- :z 让该目录可被多个容器共享使用。

docker run ... \
  -v /path/to/logs:/var/log/nginx:ro,Z \
  -v /path/to/nginxpulse_data:/app/var/nginxpulse_data:rw,Z \
  -v /path/to/pgdata:/app/var/pgdata:rw,Z \
  ...

不推荐做法：直接 chmod -R 777。这虽然省事，但权限过宽不安全，仅建议临时排查时使用。

单体部署（非 Docker）

适用于裸机或自建服务环境。需要用户自行安装 PostgreSQL。

步骤建议：

安装 PostgreSQL 并创建数据库与用户。
配置 configs/nginxpulse_config.json 中的 database.dsn。
启动服务（可使用 scripts/build_single.sh 构建后运行）。

database.dsn 示例：

"database": {
  "driver": "postgres",
  "dsn": "postgres://nginxpulse:nginxpulse@127.0.0.1:5432/nginxpulse?sslmode=disable",
  "maxOpenConns": 10,
  "maxIdleConns": 5,
  "connMaxLifetime": "30m"
}