Docker compose 一键启动

前置条件

Docker 24+ 与 Compose v2 (docker compose version 能跑通)
License Key (Docker 版授权 JWT, 由销售提供)
至少一个可用的 OpenAI 兼容图像渠道 (BaseURL + API Key)
公网或内网域名 (可选, 仅在反向代理 + HTTPS 时需要)

选哪一档

档位	适合	数据库	Redis	难度
最低启动	体验、个人 / 小团队、< 1k 用户	内置 SQLite	内置	最简单
完全启动 (推荐)	正式运营 / 长期跑	内置 Postgres	内置	简单
外接版	已有云数据库 / 多实例 / 大规模	你自己的 Postgres	你自己的 Redis	进阶

挑一档, 把对应 compose 存为 docker-compose.yml, 然后:

docker compose up -d

完成后 docker compose ps 应该看到对应服务都 up。

档 1: 最低启动 (SQLite + 内置 Redis)

零外部依赖, 适合体验。所有数据 (含图片 / 数据库 / Redis 持久化) 都落本地 ./data/, 但每个服务用独立子目录, 互不干扰。

services:
  imagic:
    image: woodchen/imagic:latest(或最新版本号)
    container_name: imagic
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      # Docker 版授权 JWT (找销售要)
      LICENSE_KEY: "替换成你的 License"

      # Redis (必选)
      REDIS_URL: redis://redis:6379/0

      # SQLite — 文件落 ./data/imagic/imagic.db
      DB_DRIVER: sqlite
      DB_DSN: /app/data/imagic.db
    volumes:
      # 仅挂 imagic 自己的目录, 不挂 ./data 整个根, 避免与 redis / postgres 卷互相覆盖
      - ./data/imagic:/app/data
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:8-alpine
    container_name: imagic-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--save", ""]
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

档 2: 完全启动 (推荐, Postgres + Redis 全自带)

正式运营建议用这一档。Postgres 数据库 + Redis 都在 compose 里跟 imagic 一起跑, 数据全部落 ./data/, 但每个服务用独立子目录 (./data/imagic / ./data/redis / ./data/postgres), 互不干扰; 一份 ./data 全量备份就能搞定。

services:
  imagic:
    image: woodchen/imagic:latest(或最新版本号)
    container_name: imagic
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      LICENSE_KEY: "替换成你的 License"
      REDIS_URL: redis://redis:6379/0
      DB_DRIVER: postgres
      # 与下面 db.environment 三项一致
      DB_DSN: postgresql://imagic:imagic@db:5432/imagic?sslmode=disable
    volumes:
      # 仅挂 imagic 自己的目录 (图片 + 本地缓存), 不挂 ./data 整个根
      - ./data/imagic:/app/data
    depends_on:
      redis:
        condition: service_healthy
      db:
        condition: service_healthy

  redis:
    image: redis:8-alpine
    container_name: imagic-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--save", ""]
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

  db:
    image: postgres:17-alpine
    container_name: imagic-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: imagic
      POSTGRES_PASSWORD: imagic
      POSTGRES_DB: imagic
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U imagic -d imagic"]
      interval: 5s
      timeout: 3s
      retries: 10

生产建议: 把 POSTGRES_PASSWORD 与 DB_DSN 里的密码同步改成强密码, 两边必须一致。

档 3: 外接 Postgres + Redis

已经有云数据库 / 云 Redis (阿里云 / 腾讯云 / AWS / Upstash 等), 或者多实例部署需要共享后端。 imagic 容器只跑应用本身。

services:
  imagic:
    image: woodchen/imagic:latest(或最新版本号)
    container_name: imagic
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      LICENSE_KEY: "替换成你的 License"

      # 改成你的 Redis 地址; 公网链路用 rediss://
      REDIS_URL: redis://:你的密码@redis-host.example.com:6379/0

      # 改成你的 Postgres 地址; 公网链路 sslmode=require, 私网 sslmode=disable
      DB_DRIVER: postgres
      DB_DSN: postgresql://imagic:你的密码@pg-host.example.com:5432/imagic?sslmode=require
    volumes:
      - ./data/imagic:/app/data

外部 PG 上需要先做的事:

创建库 imagic, 字符集 UTF8

可选: 创建专用用户并授权 (PG 15+ 还要给 schema 权限):

CREATE USER imagic WITH PASSWORD '强密码';
GRANT ALL PRIVILEGES ON DATABASE imagic TO imagic;
GRANT ALL ON SCHEMA public TO imagic;

网络放行: 服务器到 PG 的 5432 端口能通; 云数据库白名单加上服务器 IP
Redis 同样放行 6379 (或 6380 TLS), 鉴权方式见外接 Redis

外接版的 ./data/ 目录只剩本地图片缓存 (默认存储模式), 切到对象存储后这个目录基本可以为空。

拿默认 admin 密码

进程首启会自动创建管理员账号, 密码是 16 位随机字符串, 打到启动日志:

docker compose logs imagic | grep -i "初始密码"
# 示例: 初始密码: 35031ce2c331161c

打开 http://<你的服务器>:8080, 用 admin@imagic.local + 上面的密码登录。登录后第一件事去 个人中心 → 账号安全 改密码。

配置一条生图渠道

进 /admin/channels, 点 "新建":

Mode: openai (大多数代理) 或 codex_cli (codex 反代)
BaseURL: 上游接入点, 如 https://api.openai.com/v1
API Key: 上游凭证
Models: gpt-image-2 (主模型, 主键)

保存后点该渠道的 "测试" 按钮验证连通性, 通过后启用即可。详细字段见功能介绍 → 渠道。

验证生图

回到首页 → 创造, 输入任意 prompt 点 "生成"。如果一切正常, 你会看到渐进出图 → 成图 → 生成成功。失败排查见常见问答 → 生图相关。

数据存放在哪

路径	内容	适用档位
`./data/imagic/imagic.db`	SQLite 数据库	档 1
`./data/imagic/<yyyy>/<mm>/<dd>/...`	图片二进制 (本地存储模式)	全部
`./data/redis/`	Redis AOF 持久化	档 1, 档 2
`./data/postgres/`	Postgres 数据	档 2

整个 ./data 是唯一需要备份的目录 (外接版除外, 那时数据库 / Redis 各自管自己的备份)。详细备份方案见升级与备份。

升级到新版本

docker compose pull        # 拉最新镜像
docker compose up -d       # 滚动替换容器

docker-compose.yml 里 image: 也可以固定到具体版本 (如 woodchen/imagic:1.2.3), 历次版本变化见更新日志。

老版本迁移: 挂卷由 `./data` 改成 `./data/imagic`

旧文档曾建议 ./data:/app/data, 现已改为 ./data/imagic:/app/data (避免 imagic 写图片时撞上同目录里的 redis/ / postgres/ 子目录)。继续用老挂法不会损坏数据, 但若你想跟齐新约定, 按下面顺序迁移一次即可:

docker compose down                          # 停服, 文件解锁
mkdir -p data/imagic                         # 新建子目录
# 把所有"既不是 redis 也不是 postgres"的内容挪进去 (SQLite + 图片树等)
shopt -s extglob 2>/dev/null
mv data/!(imagic|redis|postgres) data/imagic/ 2>/dev/null || \
  find data -mindepth 1 -maxdepth 1 ! -name imagic ! -name redis ! -name postgres \
    -exec mv -t data/imagic/ {} +
# 改 docker-compose.yml 里 imagic.volumes 为  ./data/imagic:/app/data
docker compose up -d

停止与重启

docker compose down            # 停止并删除容器, 数据保留
docker compose down -v         # 危险: 同时删除卷, 仅在彻底重置时使用
docker compose restart imagic  # 仅重启应用, 不动数据

Docker compose 一键启动

On this page