Pinepods 0.9.0 配置参数详解

目标：讲清 Pinepods 0.9.0 的三层参数体系（部署期环境变量、运行期全局设置、用户级设置）的查看与修改方式，逐项给出实测默认值、取值影响与 MariaDB/PostgreSQL 双数据库后端及 Valkey 缓存的配置差异，并给出两档可直接落地的生产配置模板。本文所有参数值与命令回显均在 0.9.0 真实部署环境实测取得。

一、环境信息

二、前置条件

1. 已按《Pinepods Docker Compose 部署指南》完成部署并完成初始化向导（管理员 admin / q1w2e3r4）。
2. 已在 Web 界面用户设置页创建一个 API 密钥，下文记为 <你的API密钥>，认证方式为请求头 Api-Key: <你的API密钥>。
3. 修改部署期参数需要重启服务（compose 编辑 environment 后重建服务）；修改运行期设置即时生效，无需重启。

三、参数查看与修改方式

3.1 部署期：环境变量

Pinepods 应用本体没有配置文件，部署期参数全部通过环境变量注入（compose environment: 段）。查看当前生效值的最直接方式是看启动日志的关键回显行（时区、数据库类型在启动时明确打印）：

Setting timezone to Asia/Shanghai
Using mounted timezone file from host
Using postgresql database

第一行确认 TZ 已生效；第三行确认 DB_TYPE 已生效。环境变量修改后必须重启服务进程才会重新读取。

3.2 运行期：服务端配置接口与数据库存储

运行期全局设置存于数据库 AppSettings 表，并通过 API 暴露。服务端配置（发现源地址等，来自环境变量的映射结果）实测：

$ curl -s http://127.0.0.1:8140/api/data/config -H "Api-Key: <你的API密钥>"
{"api_url":"https://search.pinepods.online/api/search","proxy_url":"://873fcc63bcc4\n:/mover/?url=",...,"people_url":"https://people.pinepods.online"}

（输出节选：api_url 与 people_url 即 SEARCH_API_URL/PEOPLE_API_URL 两个环境变量的运行期取值，可据此核对注入是否生效。）

全局开关实测（数据库侧直查，管理员也可在 Web 设置页操作）：

$ psql -U postgres -d pinepods_database -c 'select selfserviceuser, downloadenabled, newsfeedsubscribed from "AppSettings";'
 selfserviceuser | downloadenabled | newsfeedsubscribed
-----------------+-----------------+--------------------
 f               | t               | f
(1 row)

三列含义：自助注册关闭（仅管理员建号）、剧集下载开启、默认新闻播客订阅标记。这些开关在 Web 管理页修改后即时生效，无需重启。

3.3 用户级：设置接口

每个用户的界面偏好（主题/语言/时区/时间格式等）存于用户记录，实测读取：

$ curl -s http://127.0.0.1:8140/api/data/my_user_info/2 -H "Api-Key: <你的API密钥>"
{"dateformat":"ISO","email":"admin@pinepods.local","fullname":"Pinepods Admin","isadmin":1,"language":"en","timeformat":24,"timezone":"UTC","userid":2,"username":"admin"}

用户在 Web 界面设置页修改即可；这些值不影响服务进程，改完刷新页面即生效。

四、参数总览

总览解读：先分清「改哪一层」——连接类与地址类在环境变量层；功能开关在管理页；界面偏好在用户设置页。跨层改错位置是新手最常见的无效修改原因。

五、核心参数分类详解

5.1 数据库连接（DB_TYPE / DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME）

六个变量构成数据库连接串，实测值与语义：

连接排障依据（实测启动日志时序）：应用启动后最多重试 30 次连接数据库，日志 Connection attempt 1/30 failed: ... Connection refused 属于数据库尚未就绪的正常重试，实测第 2 次成功；若 30 次全失败再查主机名/端口/密码。

5.2 缓存连接（VALKEY_HOST / VALKEY_PORT）

缓存健康实测：应用健康检查把缓存作为独立布尔项报告（"redis":true），缓存侧可用 valkey-cli 直接核对：

$ valkey-cli ping
PONG
$ valkey-cli config get maxmemory
maxmemory
0

实测默认 maxmemory=0 即不限制内存，由应用侧写入量决定占用；小型部署维持默认即可，资源紧张的宿主可按需在 Valkey 侧设置上限。

5.3 对外地址与发现源（HOSTNAME / SEARCH_API_URL / PEOPLE_API_URL）

三者都可用 /api/data/config 接口核对运行期取值（见 3.2 实测）。

5.4 运行身份与时区（PUID / PGID / TZ / DEFAULT_LANGUAGE）

时区注意：TZ 影响的是服务进程时间（日志时间戳），用户资料里的时区（my_user_info 的 timezone）是独立字段，实测新用户默认 UTC，需在设置页单独改。

5.5 行为开关（DEBUG_MODE / PINEPODS_AI_URL）

5.6 数据库侧参数（MariaDB 与 PostgreSQL 对照）

MariaDB（官方默认编排）关键参数实测摘录：

command: --wait_timeout=1800
environment:
  MYSQL_TCP_PORT: 3306
  MYSQL_ROOT_PASSWORD: myS3curepass
  MYSQL_DATABASE: pinepods_database
  MYSQL_COLLATION_SERVER: utf8mb4_unicode_ci
  MYSQL_CHARACTER_SET_SERVER: utf8mb4
  MYSQL_INIT_CONNECT: "SET @@GLOBAL.max_allowed_packet=64*1024*1024;"

逐项解读：utf8mb4 + utf8mb4_unicode_ci 保证中文播客名正常存取（本文实测中文订阅「声东击西」全程正常）；max_allowed_packet 放大到 64MB 与 wait_timeout=1800 是官方针对大剧集元数据导入与长连接的调优，照抄即可。

PostgreSQL（本文实测）仅三个必要变量：POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD，另用 PGDATA=/var/lib/pgdata/pgdata 指定数据目录位置以便挂载。两种后端在应用功能面完全一致，选型看团队熟悉度即可。

5.7 运行期全局设置（AppSettings）

实测三项全局开关（见 3.2 回显）：selfserviceuser=f（自助注册关闭——面向公网部署建议保持关闭，由管理员建号）、downloadenabled=t（下载功能开启——多用户共享带宽环境可关闭）、newsfeedsubscribed=f（官方新闻播客订阅标记，向导阶段选择是否订阅）。另有服务端加密密钥（encryptionkey）由首次启动自动生成，属敏感值，不要手工改动，备份数据库时随之备份。

5.8 用户级设置

实测默认值（管理员账号）：

用户级设置全部在 Web 设置页修改，即时生效；gPodder 绑定是外部客户端同步的入口，绑定后第三方客户端用生成的凭据指向 8042 端口即可同步。

六、生产配置模板

模板一：小型家用（2 核 CPU / 2GB 内存 / 40GB 磁盘，1–5 用户，不做批量下载）

关键项：应用与数据库同机部署，Valkey 维持默认不设内存上限；DEBUG_MODE=false、自助注册保持关闭；磁盘预算大头是下载目录，按「每档播客 × 保留集数 × 单集体积」估算，20GB 可存约 500 集标准音量播客。

# 与部署指南 compose 一致，差异项如下
    environment:
      DEBUG_MODE: "false"
      PUID: 911
      PGID: 911
      TZ: "Asia/Shanghai"
      HOSTNAME: "https://pod.example.com"   # 建议走反代 + HTTPS
    ports:
      - "127.0.0.1:8040:8040"               # 仅本机监听，由反代对外

模板二：团队共用（4 核 CPU / 8GB 内存 / 200GB 磁盘，5–50 用户，含视频播客）

关键项：视频播客与批量下载显著放大磁盘与带宽消耗，建议开启官方 MariaDB 编排的 64MB max_allowed_packet（大元数据导入更快）；确认 selfserviceuser 策略（团队内可开自助注册减少管理负担）；备份目录单独挂载并纳入宿主级定时备份。

    environment:
      DEBUG_MODE: "false"
      HOSTNAME: "https://pod.example.com"
      PINEPODS_AI_URL: "http://pinepods-ai:8100"   # 需 AI 转写时才启用并另起侧车

两档共同点：应用本体资源占用轻（Rust 服务），资源规划重心在数据库缓存与下载目录磁盘；模板中未展开的变量保持部署指南默认值即可。

七、常见问题（排障实录）

Q1：改了环境变量但行为没变化。 实测要点：环境变量只在服务进程启动时读取，compose 编辑后必须以 compose 重建服务（仅 restart 不更新环境）。核对是否生效用两把尺子——启动日志（TZ/DB_TYPE 有明确回显行）与 /api/data/config 接口（SEARCH_API_URL/PEOPLE_API_URL 有映射回显）。

Q2：分享链接打不开 / 客户端连不上。 HOSTNAME 写错是最常见原因：它必须是「外部实际访问地址」。实测对照：内部 compose 服务名不能当外部地址；反代场景要写 https://域名 全称。改完重启，用 Web 界面生成一条新分享链接验证。

Q3：从 MariaDB 切到 PostgreSQL（或反向）后数据「消失」。 这不是故障：DB_TYPE 切换等于连到另一个全新数据库，Pinepods 不做跨后端数据迁移。切换前先用服务自带备份功能导出（备份接口 backup_server/backup_user），切换后手动导入或重新订阅。

Q4：下载失败提示无权限写目录。 PUID/PGID=911 运行的服务对挂载目录没有写权限。在宿主侧把 downloads/backups 目录属主改为 911:911（或放开组写权限），再重试下载。

Q5：健康检查 redis:false。 缓存层不可达。依次核对：VALKEY_HOST 与缓存服务名一致、编排状态检查确认缓存服务处于 Up、缓存侧 valkey-cli ping 返回 PONG（本文实测正常态即 PONG）。

八、参考链接

• 官方配置文档：https://docs.pinepods.online
• 官方 Compose 编排文件：https://github.com/madeofpendletonwool/Pinepods/tree/main/deployment/docker
• Valkey 项目文档：https://valkey.io
• 本专栏配套文档：《Pinepods 介绍与选型指南》、《Pinepods Docker Compose 部署指南》、《Pinepods 0.9.0 API 使用详解》