Sharry 1.17.0 Docker Compose 部署指南
在 Ubuntu 22.04 上用 Docker Compose 部署 Sharry 1.17.0（PostgreSQL 18.6 后端）：镜像选型、compose 编排、登录与分享发布实测、数据持久化、SHARRY_ 环境变量覆盖、等价 docker run 与常见排障，实测通过。
Sharry 1.17.0 Docker Compose 部署指南
目标：从零开始在一台 Ubuntu 服务器上用 Docker Compose 部署 Sharry 1.17.0（PostgreSQL 18.6 作后端数据库），完成登录、分享发布、匿名下载与数据持久化验证。全部命令与回显已在 Ubuntu 22.04 实测通过。
一、环境信息
本文部署过程在以下环境实测：
- 操作系统：Ubuntu 22.04（x86_64）
- Docker 版本：29.9.2（Docker Compose v2 插件随 Docker Engine 提供）
- Sharry 版本：v1.17.0（官方镜像
eikek0/sharry:v1.17.0，GitHub Releases 最新稳定版，发布于 2026-10-05，2026-11-01 实查） - 数据库：PostgreSQL 18.6（官方
postgres:18.6镜像） - JVM 运行时：官方镜像内置 OpenJDK 17，堆参数限定
-Xms256m -Xmx512m -Xmn128m - 服务端口：Sharry 默认监听 9090；宿主机映射端口 8131
- 项目目录：
/opt/sharry/compose（compose 文件与 sharry.conf） - 数据目录：
/opt/sharry/data/pg（PostgreSQL 数据落盘） - 实测资源占用：Sharry 进程 255.7MiB 内存 / 0.11% CPU；PostgreSQL 24.86MiB / 3.60%（
docker stats --no-stream）
二、镜像选型说明
Sharry 官方只维护一个镜像仓库 eikek0/sharry，无 alpine/slim 变体之分。选型要点：
- 版本 tag 选择：固定具体版本
v1.17.0而非latest，便于回滚与复现。官方仓库另发布nightly滚动构建（每日自动构建，GitHub Releases 实查 2026-11-01），只适合尝鲜，生产不要使用； - 镜像内部结构（进入镜像实测）：入口程序
/opt/sharry/bin/sharry-restserver（/opt/sharry是指向/opt/sharry-restserver-1.17.0的软链），程序目录含bin/、conf/、lib/三层；conf/sharry.conf是镜像内置的全量默认配置（570 行、带逐项注释，2026-11-01 实测 md56254a79b5d84afdac7c71660dc38376b）； - 配置文件即启动参数：镜像以配置文件路径作为启动参数（官方 compose 即
command: /opt/sharry.conf）。启动日志会明确打印Using given config file: /opt/sharry.conf——把自建配置挂载到该路径即可整体替换默认配置，这是 Sharry 唯一的配置入口； - 健康检查：官方 compose 自带 healthcheck，探测
wget --spider http://localhost:9090/api/v2/open/info/version； - 数据库选型：官方支持 PostgreSQL、MariaDB 与 H2（进程内库）。Compose 部署建议 PostgreSQL——H2 仅适合试用评估（官方默认配置即 H2 演示库）。
💡 技术拓展：文件分享服务的容器镜像来源有两类——官方自建镜像（本文所用）与社区封装镜像（如 linuxserver.io 系列）。官方镜像随源码同源构建、发布节奏与上游一致；社区镜像常再封装更多环境变量，但存在版本滞后与维护断档风险。Sharry 官方镜像已内置默认配置与OpenJDK 运行时，生产环境建议优先官方镜像并固定版本 tag。
三、前置条件
- 服务器已安装 Docker Engine 20.10+ 与 Compose v2 插件：
docker version --format '{{.Server.Version}}'
29.9.2
- 目标端口空闲。本文预分配宿主机端口 8131，部署前实测确认未被占用：
ss -ltnp | grep :8131 || echo "8131 空闲"
8131 空闲
- 资源预算：Sharry 是 JVM 应用，官方镜像空载即占约 256MiB 内存（堆下限
-Xms256m），加上 PostgreSQL 建议预留 1GB 以上内存；磁盘按分享文件总量预估（默认文件存入数据库，见第五章）。
四、部署步骤
4.1 编写 docker-compose.yml
创建项目目录并写入编排文件：
mkdir -p /opt/sharry/compose /opt/sharry/data/pg
cat > /opt/sharry/compose/docker-compose.yml <<'EOF'
name: sharry-1.17.0-stack
networks:
sharry-net:
driver: bridge
ipam:
config:
- subnet: 10.89.57.0/24
gateway: 10.89.57.1
services:
restserver:
image: eikek0/sharry:v1.17.0
container_name: sharry-1.17.0-app
command: /opt/sharry.conf
restart: unless-stopped
environment:
- JAVA_OPTS=-Xms256m -Xmx512m -Xmn128m
networks:
- sharry-net
ports:
- "8131:9090"
volumes:
- ./sharry.conf:/opt/sharry.conf
healthcheck:
test: ["CMD-SHELL", "wget --spider http://localhost:9090/api/v2/open/info/version"]
interval: 1m
timeout: 10s
retries: 2
start_period: 30s
depends_on:
db:
condition: service_healthy
db:
image: postgres:18.6
container_name: sharry-1.17.0-db
restart: unless-stopped
networks:
- sharry-net
volumes:
- ./data/pg:/var/lib/postgresql
environment:
- POSTGRES_USER=sharry
- POSTGRES_PASSWORD=q1w2e3r4
- POSTGRES_DB=sharrydb
- PGUSER=sharry
healthcheck:
test: pg_isready -q -d sharrydb
interval: 15s
timeout: 5s
retries: 3
start_period: 15s
EOF
配置逐项说明：
name: sharry-1.17.0-stack：Compose 项目名，决定容器/网络归属分组，避免与其他项目的默认网段或项目名冲突；command: /opt/sharry.conf：把配置文件路径作为启动参数传给入口程序（见第八章挂载机制）；restart: unless-stopped：异常退出或宿主机重启后自动拉起（手动 stop 的除外）；JAVA_OPTS=-Xms256m -Xmx512m -Xmn128m：JVM 堆限定在 256–512MB。镜像启动脚本会把该变量透传给java进程，实测生效值见第十一章第 5 条；ports "8131:9090"：宿主机 8131 → 容器 9090（9090 为 Sharry 默认监听端口）；volumes（app）：宿主机配置文件挂到/opt/sharry.conf，整体替换镜像内置默认配置；volumes（db）：PostgreSQL 数据目录落到宿主机/opt/sharry/data/pg，重建容器不丢数据；networks：自定义 bridge 网络显式指定网段 10.89.57.0/24，避免与宿主机上其他网络冲突；depends_on: condition: service_healthy：先等数据库健康再启动应用，避免 Sharry 连库失败重启。
同目录写入 sharry.conf（最小可用配置，密码等敏感项生产环境建议改用环境变量注入）：
cat > /opt/sharry/compose/sharry.conf <<'EOF'
sharry.restserver {
bind {
address = "0.0.0.0"
port = 9090
}
base-url = "http://localhost:8131"
backend {
jdbc {
url = "jdbc:postgresql://db:5432/sharrydb"
user = "sharry"
password = "q1w2e3r4"
}
auth {
server-secret = "hex:5410e6a3b9c742d8f0e1d2c3a4b5968778695a4b3c2d1e0f9876543210abcdef"
session-valid = "8 minutes"
fixed {
enabled = true
user = "admin"
password = "q1w2e3r4"
order = 10
}
}
signup {
mode = "open"
}
share {
max-size = "1.5G"
max-validity = "30 days"
zip-max-size = "1.5G"
}
}
webapp {
auth-renewal = "4 minutes"
chunk-size = "10M"
default-language = "gb"
}
}
EOF
关键项说明：
bind.address = "0.0.0.0"：必须显式设置。默认值是localhost，只监听回环地址，端口映射后外部照样无法访问（实测排障过程见第十一章第 1 条）；base-url：写浏览器实际访问地址（本文http://localhost:8131）。域名/反向代理部署时改成对外完整地址，且不支持子路径部署（官方配置注释原文 "Currently deploying behind a path is not supported"）；backend.jdbc.url：Compose 网络内用服务名db直连；auth.server-secret：登录令牌的签名密钥，可用hex:/b64:前缀，多实例部署必须一致；auth.fixed：配置文件内固定账号（本文admin/q1w2e3r4），用于引导首登；内置数据库账号由internal登录模块校验（默认启用）；share.max-size：单条分享总大小上限（默认 1.5G）；max-validity有效期上限（本文放宽到 30 天，官方默认 365 天）。
4.2 启动服务
cd /opt/sharry/compose && docker compose up -d
Network sharry-1170-stack_sharry-net Creating
Network sharry-1170-stack_sharry-net Created
Container sharry-1.17.0-db Creating
Container sharry-1.17.0-db Created
Container sharry-1.17.0-app Creating
Container sharry-1.17.0-app Created
Container sharry-1.17.0-db Starting
Container sharry-1.17.0-db Started
Container sharry-1.17.0-db Waiting
Container sharry-1.17.0-db Healthy
Container sharry-1.17.0-app Starting
Container sharry-1.17.0-app Started
4.3 验证容器与启动日志
docker compose ps
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
sharry-1.17.0-app eikek0/sharry:v1.17.0 "/opt/sharry/bin/sha…" restserver 6 seconds ago Up Less than a second (health: starting) 0.0.0.0:8131->9090/tcp, [::]:8131->9090/tcp
sharry-1.17.0-db postgres:18.6 "docker-entrypoint.s…" db 6 seconds ago Up 5 seconds (healthy) 5432/tcp
等半分钟左右（JVM 启动 + 数据库迁移），日志出现服务横幅即启动完成（实测节选）：
docker logs sharry-1.17.0-app 2>&1 | head -20
2026.11.01 02:50:38:577 io-compute-3 INFO sharry.restserver.Main.run:54
Using given config file: /opt/sharry.conf
***> __ _
***> / _\ |__ __ _ _ __ _ __ _ _
***> \ \| '_ \ / _` | '__| '__| | | |
***> _\ \ | | | (_| | | | | | |_| |
***> \__/_| |_|\__,_|_| |_| \__, |
***> |___/
***> v1.17.0 (#31154b4e)
***> Base-Url: http://localhost:8131
***> Database: jdbc:postgresql://db:5432/sharrydb
***> Config: /opt/sharry.conf
***> FileRepo: DefaultDatabase(true)
横幅四行分别是生效的 Base-Url、数据库连接、配置文件路径与文件存储后端（DefaultDatabase(true) 表示文件本体存入数据库）。继续看日志确认数据库迁移与监听（实测节选）：
docker logs sharry-1.17.0-app 2>&1 | grep -E 'FlywayExecutor|Ember-Server|Started http'
2026.11.01 02:50:38:0003 [io-comp...] [INFO ] org.flywaydb.core.FlywayExecutor - Database: jdbc:postgresql://db:5432/sharrydb (PostgreSQL 18.6)
2026.11.01 02:53:15:0000 [io-comp...] [INFO ] org.http4s.ember.server.EmberServerBuilderCompanionPlatform - Ember-Server service bound to address: 0.0.0.0:9090
2026.11.01 02:53:15:0001 [io-comp...] [INFO ] sharry.restserver.RestServer.stream:37 - Started http server at http://0.0.0.0:9090/
4.4 验证 Web 页面与版本接口
curl -s -o /dev/null -w 'GET /app -> %{http_code}\n' http://localhost:8131/app/
curl -s -o /dev/null -w 'GET /api/doc -> %{http_code}\n' http://localhost:8131/api/doc
curl -s http://localhost:8131/api/v2/open/info/version
GET /app -> 200
GET /api/doc -> 200
{"version":"1.17.0","builtAtMillis":1791184276879,"builtAtString":"2026-10-05 09:11:16.879+0200","gitCommit":"31154b4ebab6e0c623a9ccb7b54691d7b8d6eb80","gitVersion":"1.17.0"}
/app/是 Web 单页应用入口，浏览器打开http://<服务器IP>:8131/app/即登录页；/api/doc是服务器自带的 REST API 交互文档（Swagger UI）；- 版本接口返回的
builtAtString与 GitHub Releases 发布时间一致，说明镜像与版本对得上。
4.5 登录验证
用配置文件 auth.fixed 段定义的账号登录（curl 实测，也是后续接口调用的认证方式）：
curl -s -X POST http://localhost:8131/api/v2/open/auth/login \
-H 'Content-Type: application/json' \
-d '{"account":"admin","password":"q1w2e3r4"}'
{"id":"G3xsRFTpFqK-pDbvZ8HdWsP-cdR4sooakgi-RN2CRvjCaHq","user":"admin","admin":true,"success":true,"message":"Login successful","token":"1793501248828-RzN4c1JGVHBGcUstcERidlo4SGRXc1AtY2RSNHNvb2FrZ2ktUk4yQ1J2akNhSHEvYWRtaW4vdHJ1ZQ==-$2a$10$6yLQKGuJ6KtQjbU0m16l3.-5v68cgv/sy3Y4s6Qn6tKgX1WLNk=","validMs":480000}
success: true 且返回签名 token（validMs: 480000 即配置的 8 分钟有效期，Web 端每 4 分钟自动续期）。浏览器侧用同一账号在登录页登录即可进入主界面。完整的 REST API 调用方法见本专栏《Sharry 1.17.0 API 使用详解》。
4.6 分享发布与匿名下载实测
登录后创建一条分享并上传文件，验证核心业务链路（完整接口说明见本专栏 API 篇）：
TOKEN=$(curl -s -X POST http://localhost:8131/api/v2/open/auth/login \
-H 'Content-Type: application/json' \
-d '{"account":"admin","password":"q1w2e3r4"}' \
| python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
printf 'sharry compose deploy test\n' > /tmp/deploy-note.txt
SID=$(curl -s -X POST http://localhost:8131/api/v2/sec/upload/new \
-H "Sharry-Auth: $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"deploy-check","validity":604800000,"maxViews":10}' \
| python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
curl -s -X POST "http://localhost:8131/api/v2/sec/upload/$SID/files/add" \
-H "Sharry-Auth: $TOKEN" -F "file=@/tmp/deploy-note.txt"
curl -s -X POST "http://localhost:8131/api/v2/sec/share/$SID/publish" \
-H "Sharry-Auth: $TOKEN" -H 'Content-Type: application/json' -d '{"reuseId":false}'
{"success":true,"message":"File(s) added"}
{"success":true,"message":"Share published."}
三条请求依次返回文件已添加、分享已发布。取发布后的公开 ID 做匿名下载验证：
PID=$(curl -s "http://localhost:8131/api/v2/sec/share/$SID" \
-H "Sharry-Auth: $TOKEN" \
| python3 -c "import sys,json;print(json.load(sys.stdin)['publishInfo']['id'])")
FID=$(curl -s "http://localhost:8131/api/v2/open/share/$PID" \
| python3 -c "import sys,json;print(json.load(sys.stdin)['files'][0]['id'])")
echo "公开链接: http://localhost:8131/app/share/$PID"
curl -s "http://localhost:8131/api/v2/open/share/$PID/file/$FID"
公开链接: http://localhost:8131/app/share/9r6WwfTsPAU-DcSthy2ceQu-ntVjpocK539-NbyxPp3VneX
sharry compose deploy test
匿名访问（不带任何登录凭据）拿到上传原文，部署闭环完成。浏览器打开公开链接即为访客下载页。
五、数据持久化说明
Sharry 有两类数据，Compose 方案的持久化落点如下：
- 数据库（账号、分享元数据、文件本体）：挂载到宿主机
/opt/sharry/data/pg。默认配置backend.files.default-store = "database"，即分享的文件本体以 chunk 形式存入 PostgreSQL（启动横幅FileRepo: DefaultDatabase(true)佐证）——备份该目录即备份全部数据。数据库内实测建了 10 张业务表：
docker exec sharry-1.17.0-db psql -U sharry -d sharrydb -c '\dt'
List of tables
Schema | Name | Type | Owner
--------+-----------------------+-------+--------
public | account_ | table | sharry
public | alias_ | table | sharry
public | alias_member | table | sharry
public | filechunk | table | sharry
public | filemeta | table | sharry
public | flyway_schema_history | table | sharry
public | invitation | table | sharry
public | publish_share | table | sharry
public | share | table | sharry
public | share_file | table | sharry
(10 rows)
filechunk 存文件分片数据，是库体积增长的主要来源。
- 配置文件：
/opt/sharry/compose/sharry.conf，与 compose 文件同目录管理。
持久化实测：docker compose down 彻底删除容器与网络后重新 up -d，此前发布的分享仍在（搜索回显）：
docker compose down && docker compose up -d && sleep 40
TOKEN=$(curl -s -X POST http://localhost:8131/api/v2/open/auth/login \
-H 'Content-Type: application/json' \
-d '{"account":"admin","password":"q1w2e3r4"}' \
| python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -s "http://localhost:8131/api/v2/sec/share/search?q=quarterly" -H "Sharry-Auth: $TOKEN"
{"items":[{"id":"F2isqTbqMai-TkxmnLjPCoz-GZSpo2mcBfg-h4CR4bvapoy","name":"quarterly-report","aliasInfo":null,"validity":604000,"maxViews":100,"password":true,"created":1793501286415,"files":1,"size":29,"published":true}]}
published: true 且文件数据完好——数据全部落盘，容器重建无损。若想改用文件系统或 S3（MinIO）存文件本体，见本专栏《Sharry 1.17.0 配置参数详解》的 backend.files 段。
六、环境变量表
Sharry 的每个配置项都可以用环境变量覆盖，优先级高于配置文件（官方配置文档 2026-11-01 实查）。命名规则：变量名不含根命名空间 sharry.restserver，其余路径段全大写、. 与 - 一律换成 _。例如 sharry.restserver.bind.address → SHARRY_BIND_ADDRESS。
| 环境变量 | 对应配置项 | 示例值 | 说明 |
|---|---|---|---|
SHARRY_BIND_ADDRESS | sharry.restserver.bind.address | 0.0.0.0 | 监听地址，默认 localhost，容器部署必改 |
SHARRY_BIND_PORT | sharry.restserver.bind.port | 9090 | 监听端口 |
SHARRY_BASE_URL | sharry.restserver.base-url | http://192.168.1.10:8131 | 对外访问地址 |
SHARRY_BACKEND_JDBC_URL | sharry.restserver.backend.jdbc.url | jdbc:postgresql://db:5432/sharrydb | 数据库连接 |
SHARRY_BACKEND_JDBC_USER | sharry.restserver.backend.jdbc.user | sharry | 数据库用户 |
SHARRY_BACKEND_JDBC_PASSWORD | sharry.restserver.backend.jdbc.password | q1w2e3r4 | 数据库密码 |
SHARRY_BACKEND_AUTH_SERVER_SECRET | sharry.restserver.backend.auth.server-secret | hex:... | 令牌签名密钥 |
SHARRY_BACKEND_AUTH_FIXED_USER | sharry.restserver.backend.auth.fixed.user | admin | 固定引导账号 |
SHARRY_BACKEND_AUTH_FIXED_PASSWORD | sharry.restserver.backend.auth.fixed.password | q1w2e3r4 | 固定账号密码 |
SHARRY_BACKEND_SIGNUP_MODE | sharry.restserver.backend.signup.mode | open / invite / closed | 注册策略 |
SHARRY_BACKEND_SHARE_MAX_SIZE | sharry.restserver.backend.share.max-size | 1.5G | 单条分享大小上限 |
SHARRY_WEBAPP_CHUNK_SIZE | sharry.restserver.webapp.chunk-size | 10M | Web 上传分块大小 |
实测验证（起了一个临时实例只给环境变量、不挂配置，观察启动日志）：给 SHARRY_BACKEND_JDBC_URL=jdbc:postgresql://db:5432/sharrydb 后，横幅 Database 行从默认 H2 变为 PostgreSQL：
***> Base-Url: http://localhost:9090
***> Database: jdbc:postgresql://db:5432/sharrydb
再给 SHARRY_BACKEND_SHARE_MAX_SIZE=1k，应用配置接口 GET /api/v2/open/info/appconfig 返回 "maxSize": 1024，启动日志同时打印上限压缩告警：
2026.11.01 02:55:16:0002 [io-comp...] [WARN ] sharry.restserver.Main.run:79 - Configuration warning: zip-max-size (1.50G) exceeds max-size (1.00K); capping to 1.00K
⚠️ 两个实测踩过的命名坑：① 变量名不能带
SHARRY_RESTSERVER_前缀——按根命名空间全称起名（如SHARRY_RESTSERVER_BACKEND_JDBC_URL）不会生效，日志仍显示默认 H2（实测复现）；② key 里的连字符要换成下划线——max-size写成SHARRY_BACKEND_SHARE_MAX-SIZE（连字符原样保留）同样不生效，必须写SHARRY_BACKEND_SHARE_MAX_SIZE。环境变量不生效时 Sharry 不报错、静默用默认值，只能靠启动横幅或 appconfig 接口核对。
七、配置参数说明
本文 compose 使用的 sharry.conf 只覆盖了最常用参数。Sharry 全部配置收敛在 sharry.restserver 命名空间下，分四大段：
bind/base-url/max-page-size：服务监听与对外地址；backend.jdbc：数据库连接（PostgreSQL / MariaDB / H2 三选一）；backend.auth：可插拔登录模块（fixed / http / http-basic / command / internal / oauth / proxy），每个模块带order优先级，按序尝试；server-secret签名令牌，session-valid控制有效期；backend.share：分享三要素上限（max-size/max-validity/zip-max-size）与require-share-password强制密码策略；backend.signup：注册三模式（open / invite / closed）；backend.files：文件存储三落点（database / filesystem / s3）与跨存储迁移（copy-files）；backend.cleanup/compute-checksum：过期清理任务（默认 14 天一轮）与后台校验和计算；webapp：界面行为（应用名、logo、语言、时区、上传分块、令牌续期间隔、初始页）；mail：SMTP 与三类邮件模板（下载就绪 / 别名页链接 / 文件送达通知）。
完整的 570 行默认配置逐段逐项解读、生产配置模板与 JVM 调优见本专栏《Sharry 1.17.0 配置参数详解》。
八、配置文件挂载
Sharry 镜像的配置加载机制（实测确认）：
- 镜像内置默认配置位于
/opt/sharry-restserver-1.17.0/conf/sharry.conf（570 行全量默认值，JVM 参数-Dconfig.file指向它）； - 入口程序接受一个参数——配置文件路径。官方镜像的默认启动参数就是
/opt/sharry.conf：- 不挂载该路径时镜像内并没有这个文件，容器会启动失败——所以官方 compose 才有
command: /opt/sharry.conf+volumes挂载的组合； - 本文 compose 把宿主机
/opt/sharry/compose/sharry.conf挂到/opt/sharry.conf，启动日志第一行即确认生效：
- 不挂载该路径时镜像内并没有这个文件，容器会启动失败——所以官方 compose 才有
Using given config file: /opt/sharry.conf
-
优先级：
SHARRY_环境变量 > 挂载的配置文件 > 镜像内置默认配置。改配置后docker compose restart restserver即可生效，无需重建容器； -
挂载注意事项：bind mount 单文件必须用绝对路径（或相对 compose 文件的
./路径）；文件内容必须是完整生效配置——它整体替换而非合并默认值，未写的段落用默认值兜底（HOCON 语义），因此从镜像内置 570 行默认配置里挑着抄是安全做法。
九、等价 docker run
与上文 Compose 完全等价的单命令启动方式（先建网络，再按依赖顺序起库与应用）：
docker network create --driver bridge --subnet 10.89.57.0/24 sharry-net
docker run -d \
--name sharry-1.17.0-db \
--network sharry-net \
--restart unless-stopped \
-v /opt/sharry/data/pg:/var/lib/postgresql \
-e POSTGRES_USER=sharry \
-e POSTGRES_PASSWORD=q1w2e3r4 \
-e POSTGRES_DB=sharrydb \
-e PGUSER=sharry \
--health-cmd 'pg_isready -q -d sharrydb' \
postgres:18.6
docker run -d \
--name sharry-1.17.0-app \
--network sharry-net \
--restart unless-stopped \
-p 8131:9090 \
-v /opt/sharry/compose/sharry.conf:/opt/sharry.conf \
-e JAVA_OPTS='-Xms256m -Xmx512m -Xmn128m' \
--health-cmd 'wget --spider http://localhost:9090/api/v2/open/info/version' \
eikek0/sharry:v1.17.0 /opt/sharry.conf
参数与 Compose 逐项对应：--network 同一自定义网络保证 db 服务名可解析、-v 数据卷与配置挂载、-e 环境变量、末尾参数 /opt/sharry.conf 即配置文件路径。日常使用仍建议 Compose 编排，depends_on 的健康检查等待与一键升级更省心。
十、常用运维命令
以下命令均在 /opt/sharry/compose 目录下执行。
# 查看运行状态与健康检查结果
docker compose ps
# 跟踪应用日志（排障首选，启动横幅/迁移/请求错误都在这）
docker logs -f sharry-1.17.0-app
# 重启应用（改完 sharry.conf 后使配置生效）
docker compose restart restserver
# 整栈重启（数据库一并重启，数据在宿主机目录不丢）
docker compose down && docker compose up -d
# 实时资源占用
docker stats --no-stream sharry-1.17.0-app sharry-1.17.0-db
NAME IMAGE STATUS
sharry-1.17.0-app eikek0/sharry:v1.17.0 Up 4 minutes (healthy)
sharry-1.17.0-db postgres:18.6 Up 4 minutes (healthy)
NAME MEM USAGE % CPU %
sharry-1.17.0-app 255.7MiB / 15.57GiB 0.11%
sharry-1.17.0-db 24.86MiB / 15.57GiB 3.60%
逻辑备份（导出账号表为例，注意表名带尾下划线 account_）：
docker exec sharry-1.17.0-db sh -c \
'pg_dump -U sharry -d sharrydb -t account_ --data-only' > account-backup.sql
--
-- PostgreSQL database dump
--
\restrict fge1RZfBEvaCXeOYDvcAMudHZ9FOV8cHJms6jd4Qk7QCCL2njTXl9TkHULp7Cy7
-- Dumped from database version 18.6 (Debian 18.6-1.pgdg13+2)
-- Dumped by pg_dump version 18.6 (Debian 18.6-1.pgdg13+2)
全量备份直接打包 /opt/sharry/data/pg（建议先 docker compose stop restserver 停写再打包）。升级：把 compose 中镜像 tag 换成新版本号，docker compose pull && docker compose up -d——Sharry 启动时由 Flyway 自动做数据库结构迁移（日志可见 Successfully validated 4 migrations），升级前照例先备份数据目录。
十一、常见问题
1. 端口映射后浏览器打不开页面
默认配置 bind.address = "localhost" 只监听回环地址，宿主机端口映射转发不到。实测复现：临时实例日志显示 Ember-Server service bound to address: 127.0.0.1:9091，外部访问超时。解决：sharry.conf 里显式 bind.address = "0.0.0.0"（或环境变量 SHARRY_BIND_ADDRESS=0.0.0.0），重启后日志变为 bound to address: 0.0.0.0:9090。
2. 页面能打开但上传/分享报 network error
base-url 与浏览器实际访问地址不一致。base-url 参与生成绝对地址（分享链接、tus 上传会话地址），实测把 base-url 留默认 http://localhost:9090 而从 8131 端口访问时，创建 tus 上传会话返回的 Location 头指向 http://localhost:9090/...，客户端后续请求全部打到错误地址。解决：base-url 必须与外部访问地址逐字一致（协议、域名/IP、端口），且不支持子路径部署——只能整域或子域对外。
3. SHARRY_ 环境变量改了配置却不生效
按第六章命名规则自查两处：是否误加了 SHARRY_RESTSERVER_ 前缀（不能带）；连字符是否换成了下划线（MAX-SIZE → MAX_SIZE）。环境变量不匹配时静默失效不报错，用启动日志横幅或 GET /api/v2/open/info/appconfig 核对生效值。
4. 启动日志有 Flyway 对 PostgreSQL 18 的 WARN
[WARN ] org.flywaydb.core.internal.database.base.Database - Flyway upgrade recommended: PostgreSQL 18.6 is newer than this version of Flyway and support has not been tested. The latest supported version of PostgreSQL is 17.
这是内置 Flyway 版本对更高数据库版本的例行提示，实测迁移与建表、读写均正常（4 次 migration 校验通过）。介意的话可把数据库换成 PostgreSQL 17。
5. JVM 堆内存的修改位置与生效验证
修改位置就是 compose 的 environment: JAVA_OPTS（或第九章 docker run -e）。实测验证生效值：
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 -Xmx512m -Xmn128m 即实际生效堆，与配置一致。内存吃紧的机器可降到 -Xms256m -Xmx256m，配合 docker stats 观察。
6. 忘记密码 / 想换管理账号
本文部署用 auth.fixed 模块——账号密码就在 /opt/sharry/compose/sharry.conf 的 fixed { user/password } 段，改完 docker compose restart restserver 生效。要换成独立数据库账号体系，启用 internal 模块并开放注册（signup.mode = "open" 或 invite），用第一个注册的账号提升管理员后关闭注册。
十二、参考链接
- 本专栏认知篇：《Sharry 介绍与选型指南》（架构、许可证、同类选型对比）
- 本专栏配置篇：《Sharry 1.17.0 配置参数详解》（HOCON 参数逐项详解与环境变量覆盖规则）
- 本专栏 API 篇：《Sharry 1.17.0 API 使用详解》（REST API 全景与排障实录）
- 官方文档站：https://eikek.github.io/sharry/
- 快速开始（Docker）：https://eikek.github.io/sharry/doc/quickstart
- 源码仓库：https://github.com/eikek/sharry
- Releases（v1.17.0，2026-10-05）：https://github.com/eikek/sharry/releases/tag/v1.17.0
- Docker Hub：https://hub.docker.com/r/eikek0/sharry
- 官方 compose 参考：https://github.com/eikek/sharry/blob/master/docker/docker-compose.yml