运行与存储

Sublink Worker 可以在 Cloudflare、Node/Vercel、Docker 上运行。为保持行为一致，运行时抽象为三层：计算、KV/Redis 存储、静态资源。本节梳理环境变量、镜像、CI 策略以及推荐的持久化方案。

存储优先级

当 Worker 启动时，会按以下优先级解析存储：

1. Redis：通过 REDIS_URL（redis://user:pass@host:port/db）或 REDIS_HOST + REDIS_PORT 连接，适用于 Docker Compose、自托管 Redis。
2. Upstash/Vercel KV：提供 KV_REST_API_URL 与 KV_REST_API_TOKEN 即可；Vercel 项目可直接引用 Vercel KV 的环境变量。
3. 内存 KV：当上述都未配置时启用，适合临时调试。若明确不希望 fallback，可设定 DISABLE_MEMORY_KV=true。

推荐在线上环境始终使用 Redis 或 Upstash KV。Config Storage 与短链都会写入 KV，选择具备持久化能力的后端可以避免订阅失效。

常用环境变量

变量	描述	默认
KV_REST_API_URL / KV_REST_API_TOKEN	Upstash / Vercel KV REST Endpoint + Token	未设置
REDIS_URL	Redis 连接 URL（优先级最高）	未设置
REDIS_HOST / REDIS_PORT	当无法提供 URL 时的 Host/Port 写法	未设置
REDIS_USERNAME / REDIS_PASSWORD	Redis 认证信息	未设置
REDIS_TLS	设为 true 时启用 TLS 连接	false
REDIS_KEY_PREFIX	为多实例共享 Redis 时的 key 前缀	未设置
CONFIG_TTL_SECONDS	KV 中基础配置的 TTL，默认 30 天	2592000
SHORT_LINK_TTL_SECONDS	短链 TTL（若运行时支持）	永不过期
STATIC_DIR	Node/Vercel 运行时静态资源目录	public
DISABLE_MEMORY_KV	禁止使用内存 KV fallback	false

所有变量均可在 Cloudflare Workers → Settings → Variables 中配置，或在 Docker/Vercel 环境下写入运行时配置。

Docker 镜像与 CI

• .github/workflows/docker-image.yml 会在 main、任意 tag 推送及手动触发时运行，构建 amd64/arm64 双架构镜像。
• 镜像统一推送到 ghcr.io/7sageer/sublink-worker，tag 包括 latest、分支/标签名以及 commit SHA，可随时回滚。
• 使用官方 Docker 镜像时：

docker pull ghcr.io/7sageer/sublink-worker:latest
docker run -p 8787:8787 -e REDIS_HOST=redis -e REDIS_PORT=6379 ghcr.io/7sageer/sublink-worker:latest

• docker-compose.yml 同时拉起 Worker 与 Redis 7，并载入 redis.conf 以启用 RDB 快照。默认数据写入 redis-data 卷，容器重启后仍可用。
• 如需调试本地代码，可执行 docker build -t sublink-worker:dev . 并设置 SUBLINK_WORKER_IMAGE=sublink-worker:dev docker compose up。

版本管理与同步

• Fork 仓库后，可通过 GitHub 的 Sync fork 保持与上游一致。
• 生产环境建议绑定 CI，例如：
  • GitHub Actions：监听 main 触发自定义 Workflow，将 pnpm run build:node 结果部署到服务器。
  • Cloudflare Pages：开启 Production branch 自动部署，并在 Preview 环境验证配置后再发布。

监控与可观测性建议

• 将 Worker 绑定到自定义域名，便于使用自家监控或日志平台。
• Redis 运行在 Docker Compose 时，可通过 redis-cli MONITOR、INFO persistence 观测读写；如接入 Upstash，可在控制台查看请求统计。
• 建议为 /shorten、/config 等写操作端点配置速率限制（可使用 Cloudflare Rules）。

下一步：配置自定义基础配置与 KV 存储，可阅读 基础配置（实验）。