PicoShare 1.5.4 配置参数详解

目标：把 PicoShare 1.5.4 的全部可配置项（启动参数、环境变量、运行期设置）逐项讲清默认值、生效方式与验证方法，并给出两套生产配置模板。全部参数在 Ubuntu 22.04 部署的 PicoShare v1.5.4 实例上实测核对。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• PicoShare 版本：v1.5.4（/information 页实测显示 1.5.4；内置 Litestream 0.3.x）
• 部署形态：单服务 Compose 部署（部署步骤见 《PicoShare 1.5.4 Docker Compose 部署指南》），对外端口 8130 → 服务监听 4001
• 数据目录：/data（Compose 卷挂载到宿主机目录）
• 参数核对日期：2026-10-30（对照官方 README 与 v1.5.4 源码逐项实测）

二、前置条件

• 已按 《PicoShare 1.5.4 Docker Compose 部署指南》完成基础部署，服务可访问；
• 会话 Cookie 有效（登录方式见该篇 4.5 节，本文实测沿用 Cookie sharedSecret=a7XY9QIgm2mimIUtd0ZWY8sETVBgF/ERlYeATvYexqw=）；
• 了解 PicoShare 的配置哲学：无配置文件，一切配置经「启动参数 + 环境变量 + 数据库内运行期设置」三条通道下发。

三、参数查看与修改方式

PicoShare 的参数分布在三个层面，查看与修改方式各不相同：

查看服务进程实际生效的环境变量（进程环境是最终生效值，涵盖编排文件与官方入口脚本注入的变量）：

cat /proc/$(pidof picoshare)/environ | tr '\0' '\n'

LITESTREAM_RETENTION=72h
PS_SHARED_SECRET=q1w2e3r4
HOSTNAME=afa2cc980e4a
PWD=/app
HOME=/root
SHLVL=0
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
DB_PATH=/data/store.db

逐项解读：PS_SHARED_SECRET 来自编排文件的 environment；LITESTREAM_RETENTION=72h 是官方构建内置的默认值——即使编排文件不设置它也生效；DB_PATH=/data/store.db 由官方入口脚本注入，供 Litestream 配置模板引用；其余 PATH/HOME/HOSTNAME/PWD/SHLVL 为进程基础环境。

查看服务进程的实际启动命令（-db 参数的来源）：

cat /proc/$(pidof picoshare)/cmdline | tr '\0' ' '; echo

/app/picoshare -db /data/store.db

运行期设置的当前值可在登录后访问 Settings 页面查看（标题实测为 PicoShare - Settings），或直接调 API 修改后重启验证。系统信息页同时暴露版本等运行事实：

curl -s -b "sharedSecret=a7XY9QIgm2mimIUtd0ZWY8sETVBgF/ERlYeATvYexqw=" http://localhost:8130/information | grep -oE "<title>[^<]*</title>|1\.5\.4" | head -3

<title>PicoShare - System Information</title>
1.5.4

四、参数总览

💡 技术拓展：口令注入的两种方式对比——PS_SHARED_SECRET 直接把明文写进环境变量（进程环境里可见，编排文件入库即明文落盘）；PS_SHARED_SECRET_FILE 指向一个文件路径（配合 secrets 文件或 bind mount 的 0600 权限文件，进程按需读取）。生产环境建议后者，至少避免口令进入编排文件的版本历史。

五、核心参数分类详解

5.1 认证与密钥参数

PS_SHARED_SECRET 是 v1.5.4 唯一必填参数，缺失时服务直接退出，实测报错：

2026/10/30 09:28:45 /app/cmd/picoshare/main.go:34: failed to read shared secret: PS_SHARED_SECRET or PS_SHARED_SECRET_FILE must be set

错误口令登录返回 401（实测）：

HTTP/1.1 401 Unauthorized
Content-Length: 22

incorrect shared secret

正确口令登录返回 200 并签发 30 天有效期的 sharedSecret Cookie（HttpOnly、SameSite=Strict，值为服务端 KDF 派生密钥而非口令本体）。登录成功后修改该变量不会使已签发的 Cookie 失效（Cookie 存的是派生密钥），因此轮换口令的同时建议重启服务让派生密钥重建，旧 Cookie 随即失效。

PS_SHARED_SECRET_FILE 用法：把口令写入文件并在 compose 中挂载，例如文件内容为 q1w2e3r4（末尾换行会被自动容忍），设置 PS_SHARED_SECRET_FILE=/run/secrets/picoshare_psk。

5.2 网络监听参数

PORT 控制服务监听端口，默认 4001（源码实测：port == "" 时回落 "4001"）。一般无需改动——改对外映射端口即可；仅当同一服务器上还有其他进程需要共用该端口时才需要调整。验证方法（对外端口可达即说明监听生效）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8130/

200

PS_BEHIND_PROXY 置为非空（惯例 true）时有两处行为变化：访问日志改按反向代理转发头（X-Forwarded-For 等）解析真实客户端 IP；API 生成的明文回显链接改用 https 协议（实测对应源码逻辑：r.TLS != nil || os.Getenv("PS_BEHIND_PROXY") != "" 时按 https://%s 拼接）。部署在 nginx/caddy 后面时务必设置，否则分享给访客的链接会错误地以 http:// 开头。

5.3 数据存储参数

-db 指定 SQLite 数据库路径，官方入口脚本固定传 -db /data/store.db（见第三章进程命令行回显），配合 /data 卷挂载完成持久化。二进制默认值为相对路径 data/store.db（服务二进制自带 --help 实测回显）：

Usage of /app/picoshare:
  -db string
    	path to database (default "data/store.db")

该路径一旦确定不要随意变更：路径变更等于切换到空库，历史文件全部「消失」（数据仍在旧文件中）。文件内容与元数据同库存储，实测上传 9MB 文件后 store.db 从 7.9MB 增至 17MB 左右——数据库体积 ≈ 已上传文件总量 + 元数据，规划磁盘时按此口径预留。SQLite 运行期伴随 -wal/-shm 文件，属正常现象；-wal 过大说明写入频繁，可临时执行 checkpoint（重启服务亦可）合并回主库。

5.4 备份参数（Litestream）

五个 LITESTREAM_* 变量中，LITESTREAM_BUCKET 是总开关：非空时入口脚本改由 litestream replicate -exec "/app/picoshare -db /data/store.db" 拉起服务，并在首次启动检测到无本地库时自动 litestream restore -if-replica-exists 恢复。备份目标为 S3 兼容对象存储（路径风格 force-path-style: true，适配 MinIO）。行为参数实测自官方仓库的 litestream.yml（v1.5.4，github.com/mtlynch/picoshare/blob/v1.5.4/litestream.yml，查询日期 2026-10-31）：

access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}
dbs:
  - path: ${DB_PATH}
    replicas:
      - type: s3
        bucket: ${LITESTREAM_BUCKET}
        path: db
        endpoint: ${LITESTREAM_ENDPOINT}
        force-path-style: true
        retention: ${LITESTREAM_RETENTION}
        snapshot-interval: 24h

（以上为官方文件原文：${...} 形态的变量引用由官方入口脚本在服务启动时用对应环境变量的实际值替换，并非需要手工填写的占位符。）

即：WAL 段准实时复制、全量快照每 24 小时一次、快照与 WAL 保留 LITESTREAM_RETENTION（默认 72h）。LITESTREAM_RETENTION 接受 Go duration 格式（如 168h、7d 之外的 240h），加大保留期可回滚到更早时点，代价是桶内存储增长。

5.5 运行期设置：默认文件存活期

登录后可修改「新上传文件的默认存活期」，API 为 PUT /api/settings，请求体两个字段：

• defaultExpirationDays：默认存活天数，合法区间 1～3650（源码限制 1 天～10 年）；
• defaultNeverExpire：布尔值，为 true 时忽略天数、新文件默认永不过期。

实测设置为 30 天：

curl -si -b "sharedSecret=a7XY9QIgm2mimIUtd0ZWY8sETVBgF/ERlYeATvYexqw=" \
  -X PUT http://localhost:8130/api/settings -H 'Content-Type: application/json' \
  -d '{"defaultExpirationDays":30,"defaultNeverExpire":false}' | head -1

HTTP/1.1 200 OK

传 0 天被拒绝（实测回显）：

Invalid request: file lifetime must be at least 1 days

该设置存入 SQLite，随数据卷持久化；它只影响之后上传文件的默认值，不追溯已有文件。单个文件上传时仍可在 expiration 参数逐个覆盖。

六、生产配置模板

6.1 小团队内网模板（2GB 内存、机械盘、纯内网）

services:
  picoshare:
    image: mtlynch/picoshare:v1.5.4
    environment:
      - PS_SHARED_SECRET=q1w2e3r4
    ports:
      - "8130:4001"
    volumes:
      - /opt/picoshare/data:/data
    restart: unless-stopped

适用场景：20 人以内团队、单文件多在几百 MB 以内、无公网暴露。不启用 Litestream，用系统级定时任务（如每日 sqlite3 /opt/picoshare/data/store.db "VACUUM INTO '/backup/pico-$(date +%F).db'"）做冷备即可。

6.2 公网模板（4GB 内存、NVMe、前置反代 + 异地备份）

services:
  picoshare:
    image: mtlynch/picoshare:v1.5.4
    environment:
      - PS_SHARED_SECRET_FILE=/run/secrets/picoshare_psk
      - PS_BEHIND_PROXY=true
      - LITESTREAM_BUCKET=prod-picoshare-backup
      - LITESTREAM_ENDPOINT=s3.example.com
      - LITESTREAM_ACCESS_KEY_ID=${PICO_AK}
      - LITESTREAM_SECRET_ACCESS_KEY=${PICO_SK}
      - LITESTREAM_RETENTION=168h
    ports:
      - "127.0.0.1:8130:4001"
    volumes:
      - /opt/picoshare/data:/data
    secrets:
      - picoshare_psk
    restart: unless-stopped

secrets:
  picoshare_psk:
    file: /opt/picoshare/secrets/picoshare_psk.txt

适用场景：对外提供分享、需要 HTTPS 与容灾。要点：端口只绑 127.0.0.1 由 nginx TLS 终结后转发；PS_BEHIND_PROXY=true 保证日志 IP 与生成链接协议正确；口令经 secrets 文件注入；备份保留期放大到 168h；PICO_AK/PICO_SK 用 shell 环境变量注入（先 export PICO_AK=实际密钥、export PICO_SK=实际密钥，再执行编排重建），避免密钥写入编排文件。

七、常见问题

7.1 修改环境变量后不生效

编排文件的 environment 改动需要重建服务实例而非原地重启：执行一次编排重建（Compose 检测到编排差异会自动重建实例，重建命令见部署指南 4.2 节）。仅重启进程（restart）不会重读编排文件。

7.2 轮换口令后旧链接还能用吗

分享给访客的下载链接不经过认证，不受口令轮换影响；已登录浏览器的会话 Cookie 有效期最长 30 天，轮换口令并重启服务后旧 Cookie 因派生密钥变化而失效，需重新登录。

7.3 磁盘占用为什么比文件总量大

SQLite 主库 + WAL 双份写入期会短暂放大占用，且删除文件后空间不会立即归还操作系统（SQLite 空页复用，不自动收缩）。需要归还空间时执行 VACUUM（或用 VACUUM INTO 生成压缩副本后替换），低峰期操作。

7.4 过期文件还在占盘

过期回收调度器每 7 小时运行一次（源码 garbagecollect.NewScheduler(&collector, 7*time.Hour)），到期文件存在最长约 7 小时的残留窗口；如需立即回收可重启服务（启动时同样触发一次清理）。

八、参考链接

• 官方 README 环境变量表：https://github.com/mtlynch/picoshare/blob/master/README.md
• Litestream 官方文档：https://litestream.io/
• SQLite VACUUM 文档：https://www.sqlite.org/lang_vacuum.html
• 本站配套文档：《PicoShare 介绍与选型指南》、《PicoShare 1.5.4 Docker Compose 部署指南》、《PicoShare 1.5.4 API 使用详解》