Docker 部署

PanSave 推荐使用 Docker Compose 部署。当前默认端口是 16868，Compose 示例默认使用 host 网络，容器会直接监听宿主机端口。

Compose 示例

services:
  pansave:
    image: pinyht/pansave:latest # PanSave 镜像，默认使用 latest 版本
    container_name: pansave # 创建后的容器名固定为 pansave
    restart: unless-stopped # 容器异常退出自动重启；手动停止后不会自动拉起
    network_mode: host # 使用宿主机网络；应用会直接监听宿主机 16868 端口
    stop_grace_period: 15m # 停止容器时最多等待 15 分钟，让已开始的后台任务自然终止
    environment: # 容器环境变量
      TZ: Asia/Shanghai # 容器时区；建议保持北京时间，保证日志和页面时间一致
    volumes: # 数据持久化挂载
      - ./data:/app/data # 持久化数据库、登录密钥、Telegram 会话、系统日志等运行数据

启动：

docker compose up -d

访问：

http://localhost:16868

如果部署在服务器或 NAS 上，把 localhost 换成设备 IP 或域名。

为什么默认使用 host 网络

PanSave 后续可能会提供更多本机端口能力，例如 302 反代相关功能。host 网络下不需要在 Compose 里逐个维护 ports 映射，配置更直接。

host 网络的含义是：应用监听的端口就是宿主机端口。默认应用监听 :16868，所以访问宿主机 16868 即可。

如果你要修改端口，可以显式设置：

environment: # 容器环境变量
  APP_ADDR: ":16869" # 应用监听地址；host 网络下会直接监听宿主机 16869 端口

然后访问 http://localhost:16869。

必须持久化 data

请保留这行挂载：

volumes: # 数据持久化挂载
  - ./data:/app/data # 持久化数据库、登录密钥、Telegram 会话、系统日志等运行数据

data 目录里至少包含：

文件或目录	用途
app.db	系统数据文件，保存配置、任务、历史和状态。
app_secret	登录状态保护文件，首次启动自动生成。
session/	Telegram 登录会话数据。
log/app.log	系统文件日志。

迁移机器或重建容器时，建议把整个 data 目录一起备份和迁移。

日志保留

应用文件日志默认写入 data/log/app.log，并使用内置轮转规则：

• 默认单个日志文件最大 10m
• 默认最多保留 7 份

Compose 示例不暴露日志路径和日志切割配置；Docker/stdout 日志保留策略交给宿主机 Docker 默认配置。

停止和更新

停止：

docker compose down

更新到最新镜像：

docker compose pull
docker compose up -d

stop_grace_period: 15m 用于给正在执行的定时任务留出收口时间。正常停止时，应用会先停止接收新请求，再等待已经开始的调度任务自然结束。

如果 host 网络不可用

少数 Docker 环境不支持 host 网络。可以改回端口映射模式：

services:
  pansave:
    image: pinyht/pansave:latest # PanSave 镜像，默认使用 latest 版本
    container_name: pansave # 创建后的容器名固定为 pansave
    restart: unless-stopped # 容器异常退出自动重启；手动停止后不会自动拉起
    stop_grace_period: 15m # 停止容器时最多等待 15 分钟，让已开始的后台任务自然终止
    environment: # 容器环境变量
      TZ: Asia/Shanghai # 容器时区；建议保持北京时间，保证日志和页面时间一致
    ports: # bridge 网络下的端口映射
      - "16868:16868" # 宿主机端口:容器端口；访问宿主机 16868 即可进入后台
    volumes: # 数据持久化挂载
      - ./data:/app/data # 持久化数据库、登录密钥、Telegram 会话、系统日志等运行数据

这种模式下，后续如果 PanSave 新增其他监听端口，需要你再手动补充对应的 ports 映射。