Slink 1.14.5 Docker Compose 部署指南

目标：从零开始在一台 Ubuntu 服务器上用 Docker Compose 部署 Slink v1.14.5 图片分享平台，完成镜像拉取、服务编排、管理员账号创建、登录与上传验证、数据持久化确认与日常运维。全部命令与回显已在 Ubuntu 24.04 实测通过。

一、环境信息

本文部署过程在以下环境实测：

操作系统：Ubuntu 24.04.5 LTS（x86_64）
Docker 版本：29.9.2（Docker Compose v5.6.1 插件）
Slink 版本：v1.14.5（官方镜像 anirdev/slink:v1.14.5，2026-10-31 发布）
服务监听端口：应用内 3000；宿主机映射端口 8130
数据目录：/opt/slink/var/data（数据库与密钥）、/opt/slink/images（图片文件）
实测资源占用：空闲内存 259.3MiB、CPU 0.15%（单实例含 PHP 与 Node 双运行时）

二、镜像选型说明

Slink 官方只维护一个镜像仓库 anirdev/slink，随源码 Release 同步构建发布。选型要点：

版本 tag 选择：固定具体版本（如 v1.14.5）而非 latest，便于回滚与复现。Slink 的镜像 tag 统一带 v 前缀，与 GitHub Releases 的 tag 命名一致，拉取时需与 Docker Hub 标签逐字一致；
镜像构成：基于 Docker 官方硬化 Alpine 基础层构建（启动横幅显示 alpine linux v3.24），内含 FrankenPHP 运行时（PHP 8.5.12）与 Node 24.22.2（SvelteKit 服务端渲染），镜像体积约 775MB——比单二进制类服务大，属 PHP+Node 双运行时的正常水位；
与旧版差异：v1.14.5 新增 USER_LOCAL_AUTH_ENABLED（可关闭本地登录，强制 SSO）；v1.12.3 起镜像基座迁移至硬化版 non-dev Alpine。

本文实测拉取（官方源直连可用，未发生降级）：

cd /opt/slink && docker compose pull   # 拉取 compose 中声明的固定版本镜像

Image anirdev/slink:v1.14.5 Pulled

本地核对镜像元数据：

docker image ls anirdev/slink          # 确认本地镜像 tag 与体积

IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
anirdev/slink:v1.14.5   776093d7c3a4        775MB          166MB   U

镜像本地解压后磁盘占用 775MB，实际内容层仅 166MB（分层去重后的真实体积）。

三、前置条件

已安装 Docker Engine 与 Compose 插件（验证方式见下）；
宿主机放行 8130 端口（可按需更换，避免与现有服务冲突）；
规划两个持久化目录（数据库与图片分离，便于备份与迁移）。

docker --version && docker compose version   # 确认运行时版本
mkdir -p /opt/slink/var/data /opt/slink/images   # 创建持久化目录

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

四、部署步骤

4.1 编写 compose 编排文件

在 /opt/slink 下创建 docker-compose.yml：

name: slink-1.14.5-stack

services:
  slink:
    image: anirdev/slink:v1.14.5
    container_name: slink-1-14-5-app
    environment:
      - TZ=Asia/Shanghai                     # 应用时区
      - ORIGIN=http://localhost:8130         # 应用对外访问地址，影响 Cookie 与跨站校验
      - USER_ALLOW_REGISTRATION=true         # 允许自助注册
      - USER_APPROVAL_REQUIRED=false         # 新用户无需管理员审批
      - USER_PASSWORD_MIN_LENGTH=6           # 口令最小长度
      - USER_PASSWORD_REQUIREMENTS=3         # 口令复杂度位掩码：1 数字 + 2 小写
      - ADMIN_USERNAME=admin                 # 首个管理员用户名
      - ADMIN_EMAIL=admin@slink.local        # 设置后触发首启自动建管
      - ADMIN_PASSWORD=q1w2e3r4              # 首个管理员口令
      - IMAGE_MAX_SIZE=15M                   # 单图上传上限
      - IMAGE_STRIP_EXIF_METADATA=true       # 剥离 EXIF 元数据
      - IMAGE_COMPRESSION_QUALITY=80         # JPEG 压缩质量
      - STORAGE_PROVIDER=local               # 存储适配器：本地磁盘
    volumes:
      - /opt/slink/var/data:/app/var/data    # 数据库、事件存储与 JWT 密钥
      - /opt/slink/images:/app/slink/images  # 上传图片文件
    ports:
      - "8130:3000"                          # 宿主机 8130 → 应用 3000
    restart: unless-stopped

逐项说明：ORIGIN 必须与实际访问地址一致（域名/IP + 端口），否则登录 Cookie 与跨站校验会失败；ADMIN_EMAIL 是首启自动建管的触发开关，只设 ADMIN_USERNAME/ADMIN_PASSWORD 不生效；USER_PASSWORD_REQUIREMENTS 为位掩码（1=数字、2=小写、4=大写、8=特殊字符，求和组合），默认 15 要求全类字符，本例设 3 以适配演示口令 q1w2e3r4。

4.2 启动服务

cd /opt/slink && docker compose up -d       # 后台启动
docker compose ps                            # 查看运行状态

NAME               IMAGE                    COMMAND                  SERVICE   CREATED          STATUS                    PORTS
slink-1-14-5-app   anirdev/slink:v1.14.5    "/usr/local/bin/entr…"   slink     20 seconds ago   Up 20 seconds (healthy)   0.0.0.0:8130->3000/tcp, [::]:8130->3000/tcp

启动即完成数据库初始化与管理员创建，观察启动日志关键段：

docker logs slink-1-14-5-app 2>&1 | head -20   # 启动横幅与初始化进度

[system:init] JWT keypair generated
[system:init] Generated Mercure JWT secret
[system:init] Generated APP_SECRET from JWT key

━━━ Slink ━━━ 1.14.5 ━━━━━━━━━━━━━━━━━━━━━━━━

[info]  engine:
            Container    docker hardened images/alpine linux v3.24
            PHP          8.5.12
            Node         24.22.2

[boot]  database provisioning ........ 2 sqlite connection(s)
[boot]  event-store schema ........... schema migrated  104ms
[boot]  read-model schema ............ schema migrated  228ms
[boot]  message queue ................ ready  92ms
[boot]  data migrations .............. 2 migration(s) executed  33ms
[boot]  image hashes ................. up-to-date
[boot]  admin user ................... admin@slink.local created  173ms

日志尾部的 admin user ... created 行说明首个管理员已按环境变量自动创建；ready in 0.64s 与 Listening on http://0.0.0.0:3000 表示服务就绪。

4.3 验证 HTTP 服务

curl -sI http://localhost:8130/ | head -4    # 首页应 302 跳转到浏览页

HTTP/1.1 302 Found
location: /explore
Date: Sat, 31 Oct 2026 03:11:53 GMT
Connection: keep-alive

用管理员账号实测登录接口（字段名为 username，值可传邮箱）：

curl -s -X POST http://localhost:8130/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin@slink.local","password":"q1w2e3r4"}' \
  -w '\nHTTP=%{http_code}\n'

{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3OTM0MTYzMzksImV4cCI6MTc5MzQxOTkzOSwicm9sZXMiOlsiUk9MRV9VU0VSIiwiUk9MRV9BRE1JTiJdLCJ1dWlkIjoiZTkzYjdkYjEtMDY5NS00OGFmLTkwZmEtMmE2NjQ5YjI4YzQwIn0.<…输出节选（实测首尾）…>","refresh_token":"c7d0694a-2311-4530-8d02-3fd8240e52e4.1796008339"}
HTTP=200

返回 200 与 access_token/refresh_token 即部署成功。浏览器访问 http://<服务器IP>:8130，用 admin@slink.local / q1w2e3r4 登录即可进入管理界面。

五、数据持久化说明

Slink 的全部状态落在两个目录，重启不丢数据：

/opt/slink/var/data → 应用内 /app/var/data：SQLite 数据库（slink.db 主库 + slink_store.db 存储元数据库）、JWT 密钥对（keys/）、应用密钥——这是必须备份的核心目录；
/opt/slink/images → 应用内 /app/slink/images：上传图片文件本体，按图片 UUID 命名落盘（如 ad765b7f-a8b3-4e3e-b423-31ee86e84578.png）。

重启验证（实测）：先记录部署后的 API Key 列表与图片分享链接，restart 后复核均存活：

cd /opt/slink && docker compose restart      # 重启服务
docker compose ps --format '{{.Name}} {{.Status}}'

Container slink-1-14-5-app Restarting
Container slink-1-14-5-app Started
slink-1-14-5-app Up 12 seconds (health: starting)

curl -s http://localhost:8130/api/user/api-keys -H "Authorization: Bearer <重启前登录获取的JWT>"   # 重启后查询
curl -sI http://localhost:8130/i/BjoZB03T | head -1                                                # 重启后访问重启前创建的分享链接

{"data":[{"id":"5e0aba44-ec4c-4ab0-992a-c73a5526722a","name":"docs-test","createdAt":"2026-10-31T11:12:52.000000+08:00","expiresAt":null,"lastUsedAt":"2026-10-31T11:13:13.000000+08:00","isExpired":false}]} [200]
HTTP/1.1 200 OK

API Key 与分享链接在重启后原样可用，持久化生效。备份策略：低峰期停写后整目录打包 var/data 与 images 即可；恢复时停服、还原目录、再启动。

六、环境变量表

部署相关核心环境变量（完整参数与默认值见《Slink 1.14.5 配置参数详解》）：

变量	作用	本文取值	不设置时默认
`ORIGIN`	对外访问地址，Cookie 与跨站校验依据	`http://localhost:8130`	`http://localhost:3000`
`TZ`	应用时区	`Asia/Shanghai`	`UTC`
`USER_ALLOW_REGISTRATION`	是否开放自助注册	`true`	`true`
`USER_APPROVAL_REQUIRED`	注册是否需管理员审批	`false`	`true`
`USER_PASSWORD_MIN_LENGTH`	口令最小长度	`6`	`6`
`USER_PASSWORD_REQUIREMENTS`	口令复杂度位掩码	`3`	`15`
`ADMIN_USERNAME`	首个管理员用户名	`admin`	`admin`
`ADMIN_EMAIL`	首个管理员邮箱（自动建管触发器）	`admin@slink.local`	不创建
`ADMIN_PASSWORD`	首个管理员口令	`q1w2e3r4`	—
`IMAGE_MAX_SIZE`	单图上传上限（k/M 后缀）	`15M`	`15M`
`IMAGE_STRIP_EXIF_METADATA`	剥离 EXIF	`true`	`true`
`IMAGE_COMPRESSION_QUALITY`	JPEG 压缩质量（1-100）	`80`	`80`
`STORAGE_PROVIDER`	存储适配器	`local`	`local`

七、配置参数说明

关键参数的行为与影响：

ORIGIN：最高频踩坑点。Slink 对写请求做同源校验，ORIGIN 与实际访问地址（含端口）不一致时，登录与上传返回 403「Cross-site POST form submissions are forbidden」。生产改为 https://<域名> 并前置反代；
ADMIN_EMAIL + ADMIN_PASSWORD：二者组合触发首次启动自动建管。仅首次启动生效，实例已有用户后再改无效；生产部署建议建管后从 compose 中移除这三个变量；
USER_PASSWORD_REQUIREMENTS：位掩码 1/2/4/8 分别要求数字/小写/大写/特殊字符，15=全要。设 3（数字+小写）即可接受 q1w2e3r4 这类演示口令；生产建议保持 15 并提高 USER_PASSWORD_MIN_LENGTH；
STORAGE_PROVIDER：切到 smb/s3 需补对应连接变量（SMB_HOST/SMB_SHARE/SMB_USERNAME/SMB_PASSWORD 或 AMAZON_S3_* 系列），此时 images 目录可不挂载，仅数据库目录需要持久化。

八、配置文件挂载

Slink 无需挂载任何配置文件：所有平台配置通过环境变量注入，运行期还可在 Web 界面 Settings 页由管理员调整（Settings 保存值优先于环境变量）。因此 compose 中只有数据卷挂载，没有配置卷。若需调整启动行为，改 environment: 段后 docker compose up -d 重建即可。

九、等价 docker run

与上述 compose 等价的单命令启动方式（便于临时验证）：

docker run -d --name slink-1-14-5-app \
  -p 8130:3000 \
  -e TZ=Asia/Shanghai \
  -e ORIGIN=http://localhost:8130 \
  -e USER_APPROVAL_REQUIRED=false \
  -e USER_PASSWORD_REQUIREMENTS=3 \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_EMAIL=admin@slink.local \
  -e ADMIN_PASSWORD=q1w2e3r4 \
  -e IMAGE_MAX_SIZE=15M \
  -e STORAGE_PROVIDER=local \
  -v /opt/slink/var/data:/app/var/data \
  -v /opt/slink/images:/app/slink/images \
  anirdev/slink:v1.14.5

生产建议仍以 compose 管理（声明式、可复制、便于升级回滚）。

十、常用运维命令

cd /opt/slink
docker compose ps                     # 服务状态与健康检查
docker compose logs -f slink          # 跟踪应用日志
docker compose restart                # 重启（验证过数据不丢）
docker compose down                   # 停止并移除服务（数据目录保留）
docker compose pull && docker compose up -d   # 升级：拉新镜像并重建

升级实测路径：将 compose 中 image: 改为新版本 tag → docker compose pull → docker compose up -d；应用启动时自动执行数据库迁移（启动日志 data migrations ... executed 行）。回滚即把 tag 改回旧版本重建（降级前建议先备份 var/data，避免新版库结构不兼容）。

十一、常见问题

Q1：登录或上传返回 403「Cross-site POST form submissions are forbidden」？ ORIGIN 与请求的实际地址不一致。核对浏览器地址栏（或 curl 的访问地址）与 ORIGIN 逐字一致（含端口、协议）。用 curl 调试写接口时需显式带同源头：-H "Origin: http://localhost:8130"（实测缺失该头必现 403，补上后 201）。

Q2：登录接口返回 422「This value should not be blank.」并提示 username？ POST /api/auth/login 的请求字段名是 username（值可传邮箱 admin@slink.local），不是 email。字段名传错即报此校验错。

Q3：首次启动没有自动创建管理员？ 三个变量必须同时设置才会触发：ADMIN_USERNAME、ADMIN_EMAIL、ADMIN_PASSWORD。只设用户名与口令不生效；日志中若无 admin user ... created 行即未触发。补救方式：临时补齐变量重建服务，或走 /profile/signup 注册（首个注册用户即管理员）。

Q4：设置的口令 q1w2e3r4 被拒绝？ 默认 USER_PASSWORD_REQUIREMENTS=15 要求含数字、小写、大写、特殊字符全部四类。演示环境可将位掩码改为 3（数字+小写），生产环境保持默认并改用强口令。

Q5：上传大图失败？ 检查 IMAGE_MAX_SIZE（上限 1000M）与反代/客户端的请求体限制是否同步调整；大文件走分片上传时受 IMAGE_CHUNK_SIZE（1M-25M）影响。

十二、参考链接

官方 Docker Compose 安装文档：https://docs.slinkapp.io/installation/01-docker-compose/
官方环境变量参考：https://docs.slinkapp.io/configuration/01-environment-variables/
First User Setup：https://docs.slinkapp.io/getting-started/03-first-user-setup/
存储适配器（SMB/S3）配置：https://docs.slinkapp.io/configuration/02-storage-provider/
GitHub Releases（版本与变更）：https://github.com/andrii-kryvoviaz/slink/releases
本文实测版本：v1.14.5（2026-10-31 发布，Releases 页实查）