Plik 1.4.3 配置参数详解

Plik 1.4.3 服务端配置文件 plikd.cfg 全参数详解：九大类参数逐项给默认值与含义，Feature 四态语义、双后端选型均配 plik -i 回读与行为实测回显，附小内存 VPS 与团队内网两档生产配置模板。

PlikPlik文件传输文件分享2026/10/31

Plik 1.4.3 配置参数详解

目标：把 Plik 1.4.3 服务端唯一配置入口 plikd.cfg 的全部参数讲透——参数怎么查看、怎么修改、怎么验证生效，九大类参数逐项给出含义、默认值与实测验证回显，并给出面向小内存 VPS 与团队内网两档的生产配置模板。全部验证均在 2026-10-31 于 Ubuntu 22.04 实机实测通过。

一、环境信息

本文实测所用的环境与材料（实测日期 2026-10-31）：

  • 操作系统：Ubuntu 22.04（x86_64）
  • Plik 版本：1.4.3（官方最新稳定版，Docker Compose 部署形态，部署过程见 《Plik 1.4.3 Docker Compose 部署指南》）
  • 配置文件基线：官方发行包样例 plikd.cfg（带逐行注释，约 130 行，覆盖 70+ 个配置项）
  • 参数生效验证工具：Plik 命令行客户端（plik -i 可回读服务端生效配置摘要）
  • 配置文件位置（部署形态）：部署目录 plikd.cfg，只读挂载到服务端 /home/plik/server/plikd.cfg
  • 组件背景见 《Plik 介绍与选型指南》

二、前置条件

  1. 已按部署指南完成 Plik 1.4.3 服务端部署并可访问（curl http://127.0.0.1:8132/health 返回 ok）；
  2. 已安装 Plik 命令行客户端（安装步骤见《Plik 1.4.3 常用 CLI 命令详解》），用于 plik -i 回读配置；
  3. 修改配置需要重启服务端进程的权限（部署形态下即 docker compose restart plik）。

三、参数查看与修改方式

3.1 配置文件的三个获取来源

Plik 服务端启动时只读取一个配置文件 plikd.cfg，获取途径有三（实测均可取得）：

  1. 官方镜像内置：官方镜像内自带样例，路径 /home/plik/server/plikd.cfg.default 附近可直接读出；
  2. 官方发行包：GitHub Releases 的 plik-server-1.4.3-linux-amd64.tar.gz 内含带注释的完整样例（sha256 eb40503e31aca0711fb85d0026aa1d225d9d32f432e7e777c769372581fca354，官方 Releases 页 sha256 清单核对，查询日期 2026-10-31）；
  3. 客户端回读生效值：plik -i 输出服务端实际生效的配置摘要（受 FeatureApiTokens 控制的接口），是验证配置改动的标准手段。

3.2 查看当前生效配置

plik --server http://127.0.0.1:8132 -i

实测回显（完整输出）：

Plik client version : 1.4.3 built from git rev d32ca8fa [mint,release] at 2026-10-22 03:18:20 +0800 CST with go1.27.3 linux/amd64

Plik server url : http://127.0.0.1:8132
Plik server version : 1.4.3

Plik server configuration :
Maximum file size : 10 GB
Maximum files per upload : 1000
Default upload TTL : 30d
Maximum upload TTL : 30d
One shot upload : enabled
Removable upload : enabled
Streaming upload : enabled
Stream timeout :
Upload password : enabled
Upload comments : enabled
Upload set TTL : enabled
Upload extend TTL : disabled
E2E encryption : enabled
Delete account : enabled
Archive compression : false
Authentication : enabled
Google authentication : disabled
OVH authentication : disabled
OIDC authentication : disabled
GitHub authentication : disabled
Local login : enabled

这份摘要按类罗列了上传限制、TTL、功能开关与认证提供方的生效值，是后续每类参数改动的统一验证手段。

3.3 修改参数与生效流程

修改配置的三步固定流程：编辑 plikd.cfg → 重启服务端 → plik -i 验证：

vim plikd.cfg                     # 编辑参数
docker compose restart plik       # 重启服务端（plikd 仅在启动时读取配置）
plik --server http://127.0.0.1:8132 -i   # 回读生效配置做确认

⚠️ 注意：plikd 不支持运行中热加载；只改文件不重启是「参数不生效」的最常见原因。

四、参数总览

plikd.cfg 采用 参数 = 值 的自有语法（字符串带双引号、数组用 []、子配置用 [段名]），全部参数按职能分九类：

分类代表参数说明
调试与日志Debug、DebugRequests、LogLevel日志级别与请求转储
HTTP 服务ListenPort、ListenAddress、Path、NoWebInterface监听、根路径、Web 界面开关
指标MetricsPort、MetricsAddressPrometheus 指标端口
TLS 与域名SslEnabled、SslCert、SslKey、TlsVersion、PlikDomain、DownloadDomain、AssumeHTTPS传输加密与公网域名
上传限制与 TTLMaxFileSizeStr、MaxUserSizeStr、MaxFilePerUpload、DefaultTTLStr、MaxTTLStr容量与生命周期
功能开关FeatureOneShot、FeatureStream、FeaturePassword、FeatureE2EE 等 15 项disabled/enabled/default/forced 四态
认证FeatureAuthentication、FeatureLocalLogin、Google/OVH/OIDC/GitHub 三元组、DefaultAdminLogin、DefaultAdminPassword、SessionTimeout五类认证提供方 + 管理员
数据后端DataBackend + [DataBackendConfig]file/S3/Swift/GCS
元数据后端[MetadataBackendConfig]SQLite/PostgreSQL/MySQL

关键差异：调试与 HTTP 类参数决定「服务怎么暴露」，上传限制与 Feature 决定「用户能干什么」，双后端决定「数据放哪里」——排障时先定位问题属于哪一类，再按下文对应小节核对参数。

五、核心参数分类详解

5.1 调试与日志参数

调试类三个参数控制日志的详略程度（配置样例与实测回显）：

Debug               = false            # Enable debug mode
DebugRequests       = false            # Log HTTP request and responses
LogLevel            = "INFO"           # Log level (DEBUG|INFO|WARNING|CRITICAL)
  • Debug：总调试开关，置 true 后启动阶段即输出 DEBUG 级细节；
  • DebugRequests：把每个 HTTP 请求与响应体打进日志，排 API 问题时开，流量大时会产生海量日志；
  • LogLevel：日志级别四档（DEBUG|INFO|WARNING|CRITICAL）。

实测验证（把三项改为 true/true/"DEBUG" 并重启后，启动日志出现 DEBUG 行，实测回显）：

[10/31/2026 01:24:24][DEBUG   ] OVH authentication : disabled
[10/31/2026 01:24:24][DEBUG   ] OIDC authentication : disabled
[10/31/2026 01:24:24][DEBUG   ] GitHub authentication : disabled
[10/31/2026 01:24:24][INFO    ] Local login : enabled

排查完毕务必改回，生产环境推荐 Debug = false、LogLevel = "INFO"。

5.2 HTTP 服务与指标参数

ListenPort          = 8080             # Port the HTTP server will listen on
ListenAddress       = "0.0.0.0"        # Address the HTTP server will bind on
Path                = ""               # HTTP root path
NoWebInterface      = false            # Disable web user interface
MetricsPort         = 0                # Port the HTTP metrics server will listen on (0 = disabled)
MetricsAddress      = "0.0.0.0"        # Address the HTTP server will bind on
  • ListenPort/ListenAddress：主服务监听；容器部署时容器内 8080 与宿主端口映射解耦，改宿主端口只需改编排文件；
  • Path：反代场景下把 Plik 挂在子路径时设置（如 /plik），直连部署留空；
  • NoWebInterface：置 true 后纯 API 服务，不托管 Web 静态资源；
  • MetricsPort：0 关闭（默认）；设为非 0 端口则另起一个 Prometheus 指标进程。

实测验证（MetricsPort = 8081 重启后，实测启动日志回显）：

[10/31/2026 01:24:24][INFO    ] Starting server at http://[::]:8080
[10/31/2026 01:24:24][INFO    ] Starting metrics HTTP server at : http://0.0.0.0:8081

在指标端口上抓取（实测回显）：

# HELP go_gc_duration_seconds A summary of the wall-time pause (stop-the-world) duration in garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0.000152089
go_gc_duration_seconds{quantile="0.25"} 0.000152089
go_gc_duration_seconds{quantile="0.5"} 0.000830072

输出为标准 Prometheus 文本格式，除 Go 运行时指标外还包含上传数量等业务指标，可直接被 Prometheus 抓取。

5.3 TLS 与域名参数

SslEnabled          = false            # Enable SSL
SslCert             = "plik.crt"       # Path to your certificate file
SslKey              = "plik.key"       # Path to your certificate private key file
TlsVersion          = "tlsv12"         # TLS version (tlsv10|tlsv11|tlsv12|tlsv13)
PlikDomain          = ""               # Public URL where the webapp is served ( ex : https://plik.root.gg )
DownloadDomain      = ""               # Enforce download domain ( ex : https://dl.plik.root.gg )
DownloadDomainAlias = []               # Set download domain aliases
AssumeHTTPS         = false            # Enable HSTS and Secure cookies
AbuseContact        = ""               # Abuse contact to be displayed in the footer of the webapp
SourceIpHeader      = ""               # If behind reverse proxy ( ex : X-FORWARDED-FOR )
UploadWhitelist     = []               # Restrict upload and user creation to one or more IP range ( CIDR notation )
  • SslEnabled/SslCert/SslKey/TlsVersion：服务端直挂证书时开启；TlsVersion 四档可选，生产建议保持 tlsv12 或 tlsv13。前置反代终结 TLS 时可不开 SslEnabled，但要设置 SourceIpHeader（如 X-FORWARDED-FOR）让服务拿到真实客户端 IP；
  • PlikDomain：对外的 Web 根地址，用于 OAuth 回调与 CORS，不限制下载域名；DownloadDomain 才是把下载强制切到独立域名的开关（可把上传域与下载域分离部署）；AssumeHTTPS 开启 HSTS 与 Secure Cookie（SslEnabled 或 https 的 PlikDomain 时自动启用）；
  • UploadWhitelist：CIDR 数组，限制哪些来源 IP 可以上传与注册，公开部署时配合反代白名单使用（如 UploadWhitelist = ["192.168.1.0/24"] 只允许内网上传）。

💡 技术拓展：上传域名与下载域名的拆分是临时文件服务的常见加固模式——

模式原理适用场景
单域名上传/下载同域个人自用、内网
上传/下载分离（PlikDomain + DownloadDomain）页面与 API 在主域，文件直链走独立域公网服务，隔离 Cookie 与文件流量、便于 CDN 化下载域
别名补充（DownloadDomainAlias）下载域多入口并存内外网双通道访问同一服务

本文部署为单机单域形态，PlikDomain/DownloadDomain 均留空走默认单域名。

5.4 上传限制与 TTL 参数

MaxFileSizeStr      = "10GB"           # 10GB (or "unlimited")
MaxUserSizeStr      = "unlimited"      # Default max uploaded size per user unless configured otherwise
MaxFilePerUpload    = 1000             # 单次上传文件数上限
DefaultTTLStr       = "30d"            # 30 days
MaxTTLStr           = "30d"            # 0 : No limit
  • MaxFileSizeStr：单文件上限，支持 10GB 这类人类可读写法与 unlimited；
  • MaxUserSizeStr：单用户累计上传量上限（unlimited 不限），可被用户级 max-user-size 覆盖；
  • MaxFilePerUpload：一次上传会话的文件个数上限；
  • DefaultTTLStr/MaxTTLStr：上传的默认与最大有效期，MaxTTLStr = 0 表示不限制时长。

实测验证（把 MaxFileSizeStr = "1GB"、DefaultTTLStr = "24h"、MaxTTLStr = "48h" 并重启，plik -i 实测回显）：

Maximum file size : 1.0 GB
Default upload TTL : 1d
Maximum upload TTL : 2d

客户端超出上限时被服务端拒绝（-t 72h 实测回显）：

unable to create upload: 400 Bad Request : unable to create upload : invalid TTL. (maximum allowed is : 172800)

（172800 秒 = 48h，与 MaxTTLStr = "48h" 精确一致。）

5.5 Feature 功能开关（四态语义）

Plik 的 15 个 Feature* 参数共用一套四态语义，这是 Plik 配置体系最重要的设计（配置样例注释原文）：

# Feature flags to enable/disable Plik features.
#  - disabled : feature is always off
#  - enabled  : feature is opt-in
#  - default  : feature is opt-out
#  - forced   : feature is always on

💡 技术拓展：四态开关的取舍——

状态语义用户侧效果
disabled永远关闭功能入口彻底消失，服务端硬拒绝
enabled可选开启（opt-in）默认不启用，用户主动勾选才生效
default可选关闭（opt-out）默认启用，用户可主动取消
forced强制开启所有上传一律带该属性，用户不可取消

拿不准时保持样例默认值即可；对安全性敏感的功能（如 OneShot）用 forced，对资源敏感的功能（如 Stream）用 disabled 直接下架。

15 个 Feature 开关一览（配置样例实测摘录）：

参数样例默认控制的功能
FeatureAuthenticationenabled账号认证体系（forced 时禁止匿名上传）
FeatureLocalLoginenabled本地登录表单
FeatureDeleteAccountenabled用户自助删除账号
FeatureOneShotenabled阅后即焚上传
FeatureRemovableenabled允许任何人删除的上传
FeatureStreamenabled流式不落盘上传
FeaturePasswordenabled密码保护上传
FeatureCommentsenabledMarkdown 评论
FeatureSetTTLenabled自定义 TTL（关闭则一律用 DefaultTTL）
FeatureExtendTTLdisabled每次访问自动延长有效期
FeatureClientsenabledWeb 界面客户端下载按钮
FeatureApiTokensenabledAPI Token（CLI 认证依赖它）
FeatureGithubenabledWeb 界面源码链接
FeatureTextenabledWeb 文本粘贴上传
FeatureE2EEenabled端到端加密

FeatureExtendTTL 样例为 disabled——过期即删的纪律性是临时文件服务的默认哲学，打开它等于允许「热文件永生」，公开部署慎开。

实测验证（FeatureComments = "disabled" 重启后）：客户端 --comments '**hello**' 上传不再报错，但评论被服务端静默丢弃——用管理员 API Token 回读该上传的元数据（实测回显）：

comments field: ''

即 disabled 的语义是「功能整体下架、参数被忽略」，而非「请求被拒绝」，排查「评论没生效」类问题时应先核对 Feature 态。

5.6 认证与管理员参数

SessionTimeout      = "365d"           # Web UI authentication session timeout
DefaultAdminLogin    = "admin"          # Login for the default admin user
DefaultAdminPassword = "q1w2e3r4"       # Password (min 8 chars). Leave empty for auto-generated.

外加五类认证提供方的三元组参数（均默认为空即未启用）：

提供方关键参数说明
本地账号FeatureLocalLogin内置用户名/口令
GoogleGoogleApiClientID/GoogleApiSecret/GoogleValidDomainsOAuth2，可限定邮箱域
GitHubGitHubApiClientID/GitHubApiSecret/GitHubValidOrganizationsOAuth App，可限定组织成员
OVHOvhApiKey/OvhApiSecret/OvhApiEndpointOVH 生态
OIDCOIDCClientID/OIDCClientSecret/OIDCProviderURL/OIDCValidDomains/OIDCRequireVerifiedEmail通用 OIDC（Keycloak 等），必须暴露 /.well-known/openid-configuration

💡 技术拓展：五类认证提供方怎么选——

提供方原理适用场景
Local服务端内置账号表个人/小团队，零外部依赖
Google/GitHub各自 OAuth2已全员持有对应账号，免管密码
OVHOVH API 认证OVH 云客户
OIDC标准 OIDC 协议对接 IdP企业统一身份（Keycloak/ADFS/Authentik 等）

本文部署使用 Local（DefaultAdminLogin/DefaultAdminPassword 自动创建的 admin 账号 + 用户自助注册），团队规模化后建议切 OIDC 统一身份。

  • SessionTimeout：Web 登录会话时长，默认 365 天，内网可放宽、公网建议缩到 7d 级别；
  • DefaultAdminPassword 留空时首启生成随机密码并打印在启动日志里；显式指定则按配置创建。实测首启日志（回显）：
[10/31/2026 01:31:10][INFO    ] Created default admin user 'admin'

已有账号时重启则显示 Default admin user 'admin' already exists, skipping creation（实测回显），即管理员创建是幂等动作，改密码配置不会覆盖已有账号——重置密码要用服务端命令 plikd user update --login admin --password <新口令>。

5.7 数据后端参数（DataBackend）

DataBackend = "file"
[DataBackendConfig]
    Directory = "/home/plik/server/data/files"

DataBackend 四选一：file（本地目录）、s3（S3 兼容）、gcs（Google Cloud Storage）、swift（OpenStack Swift），四者的 [DataBackendConfig] 段字段各不相同（配置样例给出完整字段注释）：

后端关键字段
fileDirectory
gcsBucket、Folder
swiftContainer、AuthUrl、UserName、ApiKey、Domain、Tenant
s3Endpoint、AccessKeyID、SecretAccessKey、Bucket、Location、Prefix、UseSSL、BucketLookup、PartSize、PartUploadConcurrency、SendContentMd5、SSE

S3 后端的三个值得注意的子参数（配置样例注释原文）：BucketLookup = "path" 用于 Cloudflare R2 与部分 MinIO 部署（虚拟主机式寻址会 TLS 报错）；PartSize 默认 16MiB（最小 5MiB），PartSize × 10000 即该配置下的最大可上传文件体积；PartUploadConcurrency 默认 4，调大提速但内存占用按 并发 × PartSize 放大。另有一个归档行为参数：

EnableArchiveCompression = true        # Enable zip compression for archive downloads (default: true)

控制 Web/CLI 打包下载 zip 时是否压缩：true 用 Deflate（省流量、耗 CPU），false 用 Store 仅打包（防 CPU 耗尽型 DoS）。实测改为 false 重启后，plik -i 回显 Archive compression : false。

💡 技术拓展：多实例部署时数据后端怎么选——

后端特点适用
file单机目录，随实例绑定单实例（本文形态）
s3生态最广，对接 MinIO/R2/OSS/公有云 S3多实例共享存储的首选
swiftOpenStack 生态原生已有 Swift 集群
gcsGCP 原生GCP 项目

单实例用 file 最简单；一旦要跑多实例负载均衡，必须切对象存储，否则各实例只见自己的文件。

5.8 元数据后端参数（MetadataBackendConfig）

[MetadataBackendConfig]
    Driver = "sqlite3"
    ConnectionString = "/home/plik/server/data/plik.db"
    Debug = false # Log SQL requests

Driver 三选一：sqlite3（默认，零依赖）、postgres、mysql；ConnectionString 为 GORM 连接串（SQLite 给文件路径，PG/MySQL 给 DSN）；Debug 打开后把 SQL 逐条打进日志（排库表问题用）。

💡 技术拓展：三个元数据驱动怎么选——

Driver原理/特点适用场景
sqlite3单文件嵌入式库，零运维单实例默认形态（本文采用）
postgresC/S 数据库，多写并发强多实例共享元数据的推荐选择
mysqlC/S 数据库，生态普及已有 MySQL 基础设施

与数据后端同理：单实例 sqlite3 最省心；多实例必须共享同一个 PG/MySQL，否则各实例的「上传清单」互不相认。

5.9 上传体验杂项参数

StreamTimeoutStr    = "5m"             # Max wait for a streaming download to start before releasing the upload goroutine (0 = no timeout)
WebappDirectory     = "../webapp/dist" # Root directory for webapp static content
ClientsDirectory    = "../clients"     # Root directory for client binaries
ChangelogDirectory  = "../changelog"   # Root directory for changelog
  • StreamTimeoutStr：流式上传等待下载方开始的最长时间，超时释放资源；0 不限时（下载方永不来则上传方协程一直挂着）；
  • WebappDirectory/ClientsDirectory/ChangelogDirectory：Web 静态资源、客户端二进制与更新日志的目录，镜像部署内已就位无需改动，二进制裸部署时注意相对路径以服务端工作目录为基准。

六、生产配置模板

6.1 小内存 VPS 公网模板（1–2GB 内存、单盘 20GB+）

适用：个人 VPS 对公网提供临时分享，匿名可用、收口控制：

LogLevel            = "INFO"
ListenPort          = 8080
ListenAddress       = "0.0.0.0"

MaxFileSizeStr      = "2GB"
MaxFilePerUpload    = 100
DefaultTTLStr       = "24h"
MaxTTLStr           = "7d"

FeatureOneShot      = "enabled"
FeatureStream       = "disabled"      # 公网服务关流式，防连接资源被挂住
FeatureExtendTTL    = "disabled"
FeatureAuthentication = "enabled"
FeatureLocalLogin   = "enabled"

EnableArchiveCompression = false      # 小机器省 CPU

UploadWhitelist     = []               # 如需仅内网上传：["10.0.0.0/8"]

DataBackend = "file"
[DataBackendConfig]
    Directory = "/home/plik/server/data/files"

[MetadataBackendConfig]
    Driver = "sqlite3"
    ConnectionString = "/home/plik/server/data/plik.db"

要点：文件 2GB/24h 的口径把「临时」属性做实；FeatureStream = disabled 规避长连接占用；EnableArchiveCompression = false 把归档 CPU 让给传输。

6.2 团队内网模板（4GB+ 内存、已有 PostgreSQL）

适用：内网团队服务、多实例预留、统一身份接入：

LogLevel            = "INFO"
ListenPort          = 8080
ListenAddress       = "0.0.0.0"

MaxFileSizeStr      = "10GB"
MaxTTLStr           = "30d"
DefaultTTLStr       = "7d"

FeatureAuthentication = "forced"      # 仅登录用户可上传
FeatureLocalLogin   = "enabled"
SessionTimeout      = "7d"

OIDCClientID        = "plik"
OIDCClientSecret    = "<由平台注入>"
OIDCProviderURL     = "https://keycloak.example.com/realms/myrealm"

DataBackend = "s3"
[DataBackendConfig]
    Endpoint = "minio.internal:9000"
    AccessKeyID = "<由平台注入>"
    SecretAccessKey = "<由平台注入>"
    Bucket = "plik"
    UseSSL = false
    BucketLookup = "path"

[MetadataBackendConfig]
    Driver = "postgres"
    ConnectionString = "host=pg.internal user=plik password=<由平台注入> dbname=plik sslmode=disable"

要点：forced 把匿名上传关死；OIDC 对接企业统一登录；数据/元数据双后端外置后 plikd 可水平扩多实例（对外层反代做负载均衡）。模板中密钥类值以 <由平台注入> 占位，落地时通过部署平台的密钥管理注入，禁止明文入库。

七、常见问题（FAQ）

Q1：改了 plikd.cfg 不生效？

plikd 仅在启动时读取配置。三步流程：编辑 → docker compose restart plik（或 systemd 场景 systemctl restart plikd）→ plik -i 确认。实测中 MaxFileSizeStr 等参数重启后立即在 -i 回显新值。

Q2：上传报 invalid TTL. (maximum allowed is : N)？

请求 TTL 超出 MaxTTLStr，或当前认证用户被用户级 max-ttl 限额约束（实测：全局 MaxTTLStr = "30d" 时限额 7d 的用户上传默认 30d 报 maximum allowed is : 604800）。处理：调大服务端/用户限额，或 -t 落在允许区间。

Q3：管理员密码改了配置为什么不更新？

DefaultAdmin* 只负责首次创建（幂等跳过已有账号，实测日志 already exists, skipping creation）。改密用 plikd user update --login admin --password <新口令> 或 Web 界面个人设置。

Q4：Feature 置 disabled 后客户端参数为什么还「成功」？

四态语义里 disabled 是「功能下架、参数忽略」，服务端静默丢弃该属性而不是拒绝请求（实测 FeatureComments = disabled 时上传成功但 comments 字段为空）。要「硬拒绝」语义请核对是否用错了状态组合。

Q5：SQLite 报 unable to open database file？

数据目录对运行账号（uid/gid 1000）不可写。修复属主或权限后重启（排障实录见 《Plik 1.4.3 Docker Compose 部署指南》 常见问题 Q1）。

八、参考链接

  1. Plik 官方文档站：https://root-gg.github.io/plik
  2. 配置样例（发行包内 plikd.cfg）：https://github.com/root-gg/plik/blob/master/server/plikd.cfg
  3. GitHub 仓库：https://github.com/root-gg/plik
  4. 本系列认知篇：《Plik 介绍与选型指南》
  5. 本系列部署篇：《Plik 1.4.3 Docker Compose 部署指南》
  6. 本系列命令篇：《Plik 1.4.3 常用 CLI 命令详解》