Sharry 1.17.0 配置参数详解

目标：逐段讲清 Sharry 1.17.0 服务端全部配置参数的默认值、取值范围与生效方式（配置文件 / 环境变量双层覆盖），并给出可直接落地的生产配置模板。全部参数值取自官方镜像内置默认配置实测提取，覆盖行为在 Ubuntu 22.04 实测验证。

一、环境信息

本文参数解读与实测基于以下环境：

• 操作系统：Ubuntu 22.04（x86_64）
• Sharry 版本：v1.17.0（官方镜像 eikek0/sharry:v1.17.0，2026-11-01 实查为最新稳定版）
• 数据库：PostgreSQL 18.6（官方镜像部署，连接信息 jdbc:postgresql://db:5432/sharrydb）
• JVM：镜像内置 OpenJDK 17，堆参数 -Xms256m -Xmx512m -Xmn128m
• 配置文件：部署在 /opt/sharry/compose/sharry.conf，挂载为服务端 /opt/sharry.conf
• 镜像内置默认配置：/opt/sharry-restserver-1.17.0/conf/sharry.conf（570 行，实测 md5 6254a79b5d84afdac7c71660dc38376b）
• 实测方式：修改配置或注入环境变量后重启服务，用启动日志横幅、GET /api/v2/open/info/appconfig 接口与 REST API 行为核对生效值

二、前置条件

1. 一个可运行的 Sharry 1.17.0 实例（部署过程见 《Sharry 1.17.0 Docker Compose 部署指南》，以下验证命令假定服务在 http://localhost:8131 可达）：

curl -s http://localhost:8131/api/v2/open/info/version

{"version":"1.17.0","builtAtMillis":1791184276879,"builtAtString":"2026-10-05 09:11:16.879+0200","gitCommit":"31154b4ebab6e0c623a9ccb7b54691d7b8d6eb80","gitVersion":"1.17.0"}

2. 能进入服务端查看内置默认配置（570 行、带注释，是本文参数默认值的权威出处；只读挂载的配置文件之外的默认值都在这里）：

docker exec sharry-1.17.0-app sh -c 'wc -l /opt/sharry-restserver-1.17.0/conf/sharry.conf; head -17 /opt/sharry-restserver-1.17.0/conf/sharry.conf'

570 /opt/sharry-restserver-1.17.0/conf/sharry.conf
sharry.restserver {

  # This is the base URL this application is deployed to. This is used
  # to create absolute URLs and to configure the cookie.
  #
  # Note: Currently deploying behind a path is not supported. The URL
  # should not end in a slash.
  base-url = "http://localhost:9090"

  # Maximum size when returning result lists.
  max-page-size = 100

3. 提醒一点阅读背景：Sharry 的配置是单一 HOCON 文件，根命名空间固定为 sharry.restserver；非技术读者可把 HOCON 当作"带注释和嵌套花括号的 JSON"理解即可。

三、参数查看与修改方式

Sharry 的配置有三层来源，优先级从高到低：环境变量（SHARRY_ 前缀） > 配置文件 > 镜像内置默认值。三层的查看与修改方式如下。

3.1 查看当前生效值

方式一：启动日志横幅。每次启动都会打印四个关键生效值（实测）：

docker logs sharry-1.17.0-app 2>&1 | grep -E '\*\*\*>'

***>       v1.17.0 (#31154b4e)
***>  Base-Url: http://localhost:8131
***>  Database: jdbc:postgresql://db:5432/sharrydb
***>  Config:   /opt/sharry.conf
***>  FileRepo: DefaultDatabase(true)

方式二：appconfig 接口。GET /api/v2/open/info/appconfig 无需认证，返回 Web 端使用的全部生效参数（实测节选）：

curl -s http://localhost:8131/api/v2/open/info/appconfig | python3 -m json.tool | head -20

{
    "appName": "Sharry",
    "baseUrl": "",
    "logoUrl": "/app/assets/sharry-webapp/1.17.0/img/logo.png",
    "logoUrlDark": "/app/assets/sharry-webapp/1.17.0/img/logo-dark.png",
    "iconUrl": "/app/assets/sharry-webapp/1.17.0/img/icon.svg",
    "iconUrlDark": "/app/assets/sharry-webapp/1.17.0/img/icon-dark.svg",
    "footerText": "",
    "footerVisible": true,
    "signupMode": "open",
    "oauthConfig": [],
    "chunkSize": 10485760,

时长类字段统一折算成毫秒返回：chunkSize: 10485760 即配置 chunk-size = "10M"，maxValidity: 31536000000 即默认 max-validity = 365 days，authRefreshTime: 240000 即 auth-renewal = "4 minutes"。

3.2 修改方式一：配置文件（推荐）

编辑挂载到 /opt/sharry.conf 的文件后重启服务（本文环境为 docker compose restart restserver）。配置文件只需要写与默认值不同的项——HOCON 会把自建文件叠加在内置默认值之上，没写的段用默认值兜底。

3.3 修改方式二：环境变量（覆盖优先级最高）

命名规则（官方配置文档实查，2026-11-01）：变量名以 SHARRY_ 开头，其余部分由配置项路径去掉根命名空间 sharry.restserver 后推导——每级路径段全大写，. 与 - 都替换成 _。例如：

实测验证：起一个不挂配置文件的临时实例，只给 SHARRY_BIND_ADDRESS=0.0.0.0、SHARRY_BIND_PORT=9091、SHARRY_BACKEND_JDBC_URL=jdbc:postgresql://db:5432/sharrydb 三个环境变量，启动日志显示三项全部覆盖成功（数据库从默认 H2 切到 PostgreSQL）：

    Using given config file: /opt/sharry-restserver-1.17.0/conf/sharry.conf    
***>  Base-Url: http://localhost:9090
***>  Database: jdbc:postgresql://db:5432/sharrydb

环境变量还支持官方文档描述的 HOCON 可选替换写法，在配置文件里写 mode = ${?SHARRY_BACKEND_SIGNUP_MODE} 可实现"环境变量存在则覆盖、不存在则用文件默认值"的混合注入。

3.4 生效核对与两个实测命名坑

环境变量命名错误时 Sharry 不报错、静默使用默认值，必须事后核对。实测踩过两个坑：

• ❌ 多加了根命名空间前缀：SHARRY_RESTSERVER_BACKEND_JDBC_URL 不会生效——正确名是 SHARRY_BACKEND_JDBC_URL（去掉 RESTSERVER 一级）。实测注入后者日志才切换数据库；
• ❌ 连字符没换成下划线：max-size 写成 SHARRY_BACKEND_SHARE_MAX-SIZE 不生效，必须写 SHARRY_BACKEND_SHARE_MAX_SIZE。

修改配置后除看日志外，还可以用 appconfig 接口核对数值级生效情况（见 3.1 方式二）。

四、参数总览

下表按配置段汇总 Sharry 1.17.0 全部常用参数及官方默认值（取自镜像内置 570 行默认配置）：

💡 技术拓展：配置文件格式常见三种流派——YAML（Kubernetes、Spring 系）、HOCON（Typesafe 系，Lightbend 生态）、TOML（Rust/Go 新项目常用）。Sharry 基于 Scala 生态使用 HOCON：支持注释、嵌套花括号、变量替换（${?VAR} 可选覆盖）与 include 语法，比 JSON 可读、比 YAML 少缩进陷阱。本方案实际采用官方推荐 HOCON 格式，json 后缀的配置文件它同样能读。

五、核心参数分类详解

5.1 服务监听与对外地址（bind / base-url）

这一组参数决定"服务在哪里听、别人从哪里访问"，是最容易出错的一段。

• bind.address：默认 localhost 是容器部署第一大坑。实测不修改时日志显示 Ember-Server service bound to address: 127.0.0.1:9091，端口映射后外部完全无法访问；改成 0.0.0.0 后变为 bound to address: 0.0.0.0:9090。裸机部署若只在本机使用可保留默认值以减少暴露面；
• bind.port：默认 9090，与反向代理或端口映射配合修改；
• base-url：浏览器实际访问的完整地址（协议+主机+端口）。它参与三件事：分享公开链接的生成、cookie 的作用域、tus 断点续传会话的 Location 地址。实测当 base-url 留默认 http://localhost:9090 而外部从 8131 访问时，创建 tus 上传会话返回的响应头是 Location: http://localhost:9090/api/v2/sec/upload/...——客户端后续续传请求全部打到错误地址。因此 base-url 必须与外部访问地址逐字一致；
• 子路径部署：官方注释明文 Currently deploying behind a path is not supported，只能整域名（https://sharry.example.com）或子域名（https://sharry.example.com 之外的独立子域）方式对外，不能挂在 https://example.com/sharry/ 这类路径下；
• max-page-size：列表类接口单页返回上限，调用方传更大的 pageSize 会被截到该值；
• file-download.download-chunk-size：对 range 下载请求服务端单次回送的数据量，影响大文件在线拖动播放的平滑度，一般无需改动。

5.2 数据库连接（backend.jdbc）

默认是进程内 H2 文件库（jdbc:h2://…/sharry-demo.db;MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE），仅适合试用。生产三选一：

• PostgreSQL（本文实测所用）：url = "jdbc:postgresql://db:5432/sharrydb"，user/password 对应数据库账号。文件本体默认也入库（filechunk 表），库体积约等于文件总量，规划磁盘时按此估算；
• MariaDB：jdbc:mariadb://host:3306/sharrydb。注意官方 v1.15.0 曾公告 MariaDB/H2 存在分页排序缺陷（issue #1643），v1.16.0 起修复——MariaDB 用户不要停留在 1.15.x；
• H2：保持默认即可试用，但多实例/升级风险高，不建议生产。

改库只需换 url/user/password 三项，首次启动 Flyway 自动建表（实测 10 张业务表 + flyway_schema_history）。

5.3 认证与会话（backend.auth）

令牌与签名：

• server-secret：登录令牌的签名密钥，支持 hex: 与 b64: 前缀。默认 hex:caffee 仅供演示，生产必须换成足长随机值；多实例部署必须一致，否则令牌跨实例校验失败；
• session-valid：令牌有效期，默认 8 minutes。实测登录响应 validMs: 480000 与之吻合；
• 与 webapp.auth-renewal 的联动约束：官方注释要求 renewal 间隔至少比 session-valid 早 30 秒（默认 4 分钟 vs 8 分钟），保证续期总在过期前完成。

七个登录模块（按 order 从小到大依次尝试，命中即停）：

本文部署实测启用 fixed（enabled = true，账号 admin/q1w2e3r4），登录接口返回 user: admin, admin: true。oauth 模块每个提供方需要 authorize-url/token-url/user-url/user-id-key/client-id/client-secret 六项，默认配置里已内置 GitHub、Google、Azure AD 三个模板，取消注释换上凭据即可启用。

5.4 注册策略（backend.signup）

• mode = open：任何人可注册（本文实测 POST /api/v2/open/signup/register 直接创建成功）；
• mode = invite：注册需提供邀请码，管理员凭 invite-password 调 POST /api/v2/admin/signup/newinvite 生成，invite-time（默认 14 天）控制邀请码有效期；
• mode = closed：关闭注册，账号由管理员手工建立；
• invite-password：生成邀请码的口令，默认 generate-invite，invite 模式下务必修改。

5.5 分享策略（backend.share）

• chunk-size = "512K"：文件写入数据库/存储时的分片大小，影响 filechunk 表行数，无需改动；
• max-size = "1.5G"：单条分享总大小上限。实测其服务端强制点在 tus 上传路径——用环境变量把上限压到 1k 后，通过 tus 初始化上传 2KB 文件返回 413：

== tus init 2KB (limit 1k) ==
max size exceeded
HTTP 413

⚠️ 值得注意的实测细节：普通 multipart 接口 POST /sec/upload/{id}/files/add 在同样条件下并不拦截超限文件（实测 2KB 文件照常入库成功，仅发布环节不校验）。也就是说 max-size 的强制执行依赖 Web 端默认的 tus 上传路径与前端预检，脚本直接调 multipart 接口时服务端不设防——对外网开放 multipart 端点的部署应靠反向代理限制请求体大小兜底；

• max-validity = 365 days：分享有效期上限，Web 端有效期下拉框与 API 的 validity 都不得超过它；
• zip-max-size = "1.5G"：ZIP 打包下载的总量上限，设 0 可彻底关闭该功能；超过 max-size 时启动即截断并告警（实测日志）：

[WARN ] sharry.restserver.Main.run:79 - Configuration warning: zip-max-size (1.50G) exceeds max-size (1.00K); capping to 1.00K

• require-share-password = false：v1.17.0 新增，设 true 后所有分享强制带密码（API 侧同步强制）；
• database-domain-checks：把数据库层错误翻译成友好提示的钩子，官方示例是 PostgreSQL pg_snakeoil 扩展的病毒检测约束（safe_bytea 域校验失败时返回 422 "The uploaded file contains a virus!"），默认关闭。

5.6 文件存储（backend.files）

default-store 从 stores 里选一个已启用的 id，三种类型：

• database（默认启用）：文件本体进数据库，部署最简单，备份即备库；
• filesystem：type = "file-system"，directory 指定落盘目录（注意默认值 /some/directory 是占位，必须改），clean-empty-dirs 控制清理空目录；
• minio：type = "s3"，配 endpoint/access-key/secret-key/bucket，对接 MinIO 等 S3 兼容存储，多实例部署的首选。

copy-files 段提供跨存储迁移：enable = true + source/target 指向 stores 的 id，启动时把文件从源存储拷贝到目标（只拷不删），迁完后建议把 enable 关回去。实测多实例部署时的推荐组合是 minio 存储 + 共享数据库 + 相同 server-secret。

5.7 后台任务（compute-checksum / cleanup）

• compute-checksum：上传完成后异步计算校验和。capacity = 5000 是待计算队列长度（满则上传阻塞），parallel = 0 表示并行度交由 use-default = true 接管（按 CPU 核数 -1 计算，单核机器取 1）。设 enable = false 可完全关闭（分享详情将看不到校验和字段）；
• cleanup：周期清理任务，interval = 14 days 每轮执行，回收"过期超过 invalid-age = 7 days"的已发布分享与过期邀请码。实测启动日志印证：

[INFO ] sharry.backend.job.PeriodicCleanup.logStarting:61 - Periodic cleanup job active and will run every 14.0 days. Will remove published shares expired for at least 7.0 days.

5.8 Web 界面行为（webapp）

• app-name/app-icon/app-logo/app-footer：品牌四件套，均为 URL 或 Markdown（footer），暗色主题用 -dark 后缀项单独配置；
• chunk-size = "10M"：Web 端单次请求传输的分块大小，官方注释明确"调大通常更快，默认保守"。实测 appconfig 返回 chunkSize: 10485760；
• retry-delays = [0, 3000, 6000, 12000, 24000, 48000]：tus 上传失败后的重试节奏（毫秒数组），数组长度即重试次数（默认 6 次）；
• auth-renewal = "4 minutes"：Web 端令牌续期节奏（约束见 5.3）；
• default-language = "gb"：默认语言，v1.17.0 已内置德、法、西、意、日、捷克、巴西葡语等；
• default-validity = 7 days / initial-page / initial-theme：新建分享的预选有效期与登录后落点页、初始主题；
• default-timezone：v1.17.0 新增。时间戳按"用户设置 > 浏览器自动探测 > 该默认值 > UTC"四级优先展示，不设置即保持 UTC；
• auto-publish-enabled = false：v1.17.0 新增，开启后用户可在设置页选择"传完自动发布"，设为 false 则整个特性隐藏；
• oauth-auto-redirect：只配了一个 OAuth（或 Proxy）提供方时登录页自动跳转，同时隐藏登出按钮；
• custom-head：注入 HTML head 的自定义片段（可先按本地文件路径解析、成功则内嵌其内容，否则原样渲染）。

5.9 邮件通知（backend.mail）

enabled = false 时整个邮件功能关闭（包括通知）。启用后必须给 smtp 段：host/port、user/password（user 留空则匿名发送）、ssl-type（none/starttls/ssl）、check-certificates（自签证书场景可关）、timeout、default-from（留空用当前用户邮箱）、list-id（邮件 List-Id 头，默认 Sharry）。三类 Mustache 模板可整段覆盖：download（下载就绪，{{{url}}}/{{user}}/{{#password}} 分支）、alias（别名页链接投递）、upload-notify（别名页收到文件时通知归属用户，可用 {{aliasName}}）。

5.10 日志（logging）

format 四选一（Fancy 是启动横幅那种彩色缩进格式，采集日志建议 Json 或 Logfmt）；minimum-level = Warn 是全局门槛，levels 按 logger 名覆盖——默认已把 sharry、org.flywaydb、binny、org.http4s 四个提到 Info。排障时可临时把 sharry 提到 Debug。

5.11 别名页成员协作（alias-member-enabled）

alias-member-enabled = true（默认）允许把其他用户加进别名页（alias_member 表），经该别名页上传的分享自动对成员可见。关闭后相应 REST 接口与表单元素一并移除。

5.12 JVM 堆内存（JAVA_OPTS）

Sharry 是 JVM 应用，堆内存不在 HOCON 里配置，而由启动命令的 JAVA_OPTS 环境变量控制。本文部署在 compose 的 environment 段注入 -Xms256m -Xmx512m -Xmn128m（256–512MB 限定，避免默认大堆挤占宿主内存）。实测验证生效值：

docker exec sharry-1.17.0-app jps -v

1 Main -Xms256m -Xmx512m -Xmn128m -Dconfig.file=/opt/sharry-restserver-1.17.0/bin/../conf/sharry.conf
118 Jps -Dapplication.home=/usr/lib/jvm/java-17-openjdk -Xms8m -Djdk.module.main=jdk.jcmd

1 Main 行的参数列表即实际生效堆；小内存机器可收紧到 -Xms256m -Xmx256m，配合 docker stats（实测空载 255.7MiB）观察。

六、生产配置模板

适用场景：8GB 内存 / SSD 磁盘的中小团队内网文件分享服务，PostgreSQL 独立库、invite 邀请注册、文件落本地磁盘（或按需切 MinIO）、开启邮件通知。直接替换域名、密钥与数据库凭据即可使用：

sharry.restserver {

  # 对外完整地址（不支持子路径，结尾不要斜杠）
  base-url = "https://sharry.example.com"

  bind {
    address = "0.0.0.0"
    port = 9090
  }

  backend {
    jdbc {
      url = "jdbc:postgresql://db:5432/sharrydb"
      user = "sharry"
      password = "q1w2e3r4"
    }

    auth {
      # 生产必须换随机密钥（hex: 或 b64: 前缀），多实例必须一致
      server-secret = "hex:5410e6a3b9c742d8f0e1d2c3a4b5968778695a4b3c2d1e0f9876543210abcdef"
      session-valid = "8 minutes"

      # 引导管理员：首次登录后建议改回 enabled = false
      fixed {
        enabled = true
        user = "admin"
        password = "q1w2e3r4"
        order = 10
      }
      internal {
        enabled = true
        order = 50
      }
    }

    # 邀请码注册，口令务必修改
    signup {
      mode = "invite"
      invite-time = "14 days"
      invite-password = "change-me-invite"
    }

    share {
      max-size = "2G"
      max-validity = "30 days"
      zip-max-size = "2G"
      require-share-password = false
    }

    files {
      default-store = "filesystem"
      stores = {
        database = { enabled = true, type = "default-database" }
        filesystem = {
          enabled = true
          type = "file-system"
          directory = "/opt/sharry/files"
          clean-empty-dirs = true
        }
      }
    }

    cleanup {
      enabled = true
      interval = "7 days"
      invalid-age = "3 days"
    }
  }

  webapp {
    app-name = "Sharry"
    chunk-size = "25M"
    auth-renewal = "4 minutes"
    default-language = "gb"
    default-timezone = "Asia/Shanghai"
    default-validity = 7 days
  }

  mail {
    enabled = true
    smtp {
      host = "smtp.example.com"
      port = 465
      user = "sharry@example.com"
      password = "${SMTP_PASSWORD}"
      ssl-type = "ssl"
      default-from = "sharry@example.com"
    }
  }
}

模板要点解读：

• 内存适配：该模板配合 JAVA_OPTS=-Xms256m -Xmx512m -Xmn128m 使用，整机 8GB 内存下 PostgreSQL（shared_buffers 1–2GB）+ Sharry 堆 512MB + 操作系统余量充足；文件转 filesystem/minio 存储后数据库只存元数据，库体积不再随文件量增长；
• max-size = "2G"：内网万兆环境下可按需上调；对外网部署建议不超过 1–2G 并配合反代请求体限制；
• cleanup 收紧到 7 天/3 天：过期分享及早回收，避免 filechunk 无限膨胀；
• chunk-size = "25M"：内网大带宽下把 Web 上传分块调大（官方注释：调大通常更快）；
• ${SMTP_PASSWORD}：SMTP 密码用环境变量注入（compose 的 environment: SMTP_PASSWORD=...），避免明文进配置文件仓库。

七、常见问题

1. 环境变量改了配置却不生效

按第三章 3.4 核对命名：不能带 SHARRY_RESTSERVER_ 前缀、连字符要换下划线。环境变量错误静默失效，用启动横幅或 GET /api/v2/open/info/appconfig 核对生效值。

2. base-url 到底该填什么

填浏览器地址栏里访问 Sharry 的完整地址。反代场景填反代对外的 https://sharry.example.com（反代再把流量转给 9090），直连场景填 http://<IP>:<端口>。判断是否配对的实测方法：调 tus 上传初始化接口看响应 Location 头是否指向外部可达地址。

3. zip-max-size 的告警要不要处理

Configuration warning: zip-max-size (…) exceeds max-size (…); capping to … 说明 zip 上限被自动压到 max-size。功能上无碍，但建议把两个值改成一致，消除每次启动的告警。

4. 上传大文件被 413 拒绝

返回体是 max size exceeded、状态码 413——超过了 share.max-size（强制点在 tus 初始化，见 5.5）。调大该值或改用不超过上限的分包策略；同时确认反向代理自身（nginx client_max_body_size 等）没有更小的限制。

5. 时区/时间显示不对

按 5.8 的四级优先检查：用户设置页的时区 > 浏览器自动探测 > webapp.default-timezone > UTC。服务器侧建议直接配 default-timezone = "Asia/Shanghai" 兜底。

6. 密码/密钥类配置的注入方式

server-secret、SMTP 密码等敏感项两种安全写法：HOCON 的 ${?ENV_VAR} 可选替换（第三章 3.3），或直接用对应的 SHARRY_BACKEND_AUTH_SERVER_SECRET 等环境变量覆盖配置文件。不要把生产密钥写进进版本库的配置文件。

八、参考链接

• 官方配置文档（参数与环境变量命名规则）：https://eikek.github.io/sharry/doc/configure
• 官方默认配置（reference.conf）：https://github.com/eikek/sharry/blob/master/modules/restserver/src/main/resources/reference.conf
• 部署环境与镜像信息：https://github.com/eikek/sharry（v1.17.0，2026-11-01 实查）
• 安装与 Java 版本要求：https://eikek.github.io/sharry/doc/install
• 本专栏部署实测：《Sharry 1.17.0 Docker Compose 部署指南》
• 本专栏认知篇：《Sharry 介绍与选型指南》（架构、许可证、同类选型对比）
• 本专栏 API 篇：《Sharry 1.17.0 API 使用详解》（REST API 全景与排障实录）