外接 Redis

接 ElastiCache / 阿里云 Redis / 自建 Redis, 让多实例共用同一份事件总线

Redis 在 Imagic 里不是缓存, 而是关键基础设施:

异步生图任务事件总线 (Redis Stream + Pub/Sub), 客户端断开重连不丢事件
跨进程取消信号 (Pub/Sub channel imagic:cancel:<id>)
session HMAC 密钥持久化 (key imagic:session:hmac_key), 重启 / 多实例不踢下线

启动期 ping 不通直接 fatal, 不会静默降级。单实例部署也建议保留独立的 Redis, 不要省掉; 占用极小, 收益是 session 密钥重启不丢、未来扩到多实例无需迁移。

切到外部 Redis

修改 imagic.environment.REDIS_URL, 同时注释掉或移除 compose 中的 redis 服务声明 (不再依赖内置 redis, 没必要保留容器)。

services:
  imagic:
    environment:
      REDIS_URL: redis://:strongpass@redis.your-domain.com:6379/0
    depends_on:
      # redis: 已外接, 删除或注释这一段
      db:
        condition: service_healthy
        required: false

REDIS_URL 支持的格式:

形态	示例
无密码	`redis://host:6379/0`
带密码	`redis://:password@host:6379/0`
带用户名 + 密码 (Redis 6 ACL)	`redis://user:password@host:6379/0`
TLS (rediss)	`rediss://:password@host:6380/0`

/0 是数据库编号, 默认 0; 如果该 Redis 实例还被别的服务使用, 建议给 Imagic 单独分一个 db (如 /3) 避免 key 冲突。

各厂商接入示意

AWS ElastiCache (Redis OSS)

开 Encryption in transit 时连接串用 rediss://
ElastiCache 不支持 ACL 时只有 auth-token, 走 rediss://:<token>@<endpoint>:6379/0
集群模式 (cluster-mode enabled) 暂不支持, Imagic 用的 go-redis client 是普通模式; 请用单分片 (cluster-mode disabled) 的副本组

阿里云 Redis

选"标准版" (主从) 即可, 不要选"集群版"
公网访问需要在白名单加上服务器 IP, 建议走 VPC 内网
连接串: redis://:<password>@<r-xxx>.redis.rds.aliyuncs.com:6379/0

腾讯云 Redis

同样选"标准版"
默认开了 ACL, 用户名一般是空 (即只用密码), 串 redis://:<password>@<host>:6379/0

Cloudflare Workers KV / Upstash

Upstash Redis 完全兼容, 连接串走 rediss://...@...:6379/0 (默认开 TLS)
注意 Upstash 免费档有连接数 / 带宽上限, 评估生图并发量

自建 Redis (容器外)

docker run -d --name redis-imagic \
  -p 127.0.0.1:6379:6379 \
  -v /opt/redis-imagic:/data \
  redis:8-alpine \
  redis-server --appendonly yes --save "" --requirepass strongpass

然后 REDIS_URL=redis://:strongpass@host.docker.internal:6379/0 (容器内访问宿主机) 或 redis://:strongpass@<服务器内网IP>:6379/0。

持久化建议

Imagic 写入 Redis 的 key 类型与重要程度:

Key 模式	用途	持久化重要度
`imagic:session:hmac_key`	session 签名密钥	高 — 丢了会踢所有用户下线
`imagic:gen:<id>` (Stream)	异步生图事件流, 1h TTL	中 — 丢了影响断线续连
`imagic:gen:ev:<id>` (Pub/Sub)	partial 帧	低 — 实时数据, 不需要持久化
`imagic:cancel:<id>` (Pub/Sub)	取消信号	低 — 同上

官方 compose 模板里的 Redis 默认开了 AOF (appendonly yes), 重启不丢密钥。外接 Redis 时也建议开 AOF 或 RDB, 至少保证 imagic:session:hmac_key 在 Redis 重启后还在。

如果你的外部 Redis 是纯内存模式 (无持久化), session 密钥丢失后 imagic 启动会自动写入新密钥, 副作用是所有已登录用户的 cookie 失效 (需要重新登录), 不影响数据安全。

验证

docker compose exec imagic wget -qO- http://localhost:8080/api/v1/health
docker compose logs imagic | grep -i redis
# 期望看到 ping 通的日志, 不应出现 "redis ping failed"

On this page