Image-Chat Gateway (img2chat-proxy)

专为 OpenAI 标准生态设计的轻量级 Image <-> Chat 互转与图床转存网关。内置现代 Web 配置管理控制台（/admin），无需安装任何运行时依赖。

---

一、 Linux 极简一键部署 (推荐)

在 Linux 服务器上执行以下命令，即可一键下载最新 Release 并完成 Systemd 服务安装：

# 1. 下载最新发布的 Linux 部署包并解压 (或前往 GitHub Releases 页面下载)
mkdir -p /tmp/img2chat && cd /tmp/img2chat
curl -sL https://github.com/cfwasd/image-proxy/releases/latest/download/img2chat-proxy-linux-x64.tar.gz | tar -xz

# 2. 执行交互式安装脚本 (支持自定义端口，默认 8080，自动配置开机自启并启动)
sudo ./install.sh

脚本将全自动完成：

• 部署可执行文件至 /opt/images-gateway；
• 注册并启动 /etc/systemd/system/img2chat-proxy.service 服务；
• 配置进程守护、开机自启与故障自动重启策略。

常用 systemd 管理运维命令

systemctl status img2chat-proxy    # 查看服务当前状态
systemctl restart img2chat-proxy   # 重启网关服务
systemctl stop img2chat-proxy      # 停止网关服务
journalctl -u img2chat-proxy -f    # 实时查看输出日志

---

二、 自定义端口运行方式

1. 命令行参数启动：

   ./img2chat-proxy-linux-x64 -p 9090
   # 或者
   ./img2chat-proxy-linux-x64 --port 9090

2. 环境变量启动：

   PORT=9090 ./img2chat-proxy-linux-x64

3. 修改 Systemd 端口： 编辑 /etc/systemd/system/img2chat-proxy.service 中 ExecStart 的 -p <端口>，然后执行：

   systemctl daemon-reload && systemctl restart img2chat-proxy

---

三、 Nginx 反向代理配置 (支持嵌套反代与生图长超时)

配置文件模板位于 deploy/nginx-gateway.conf。本项目管理 API 均收口在 /admin 下，即使嵌套反代也不会污染全局路由：

server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate     /etc/nginx/ssl/api.yourdomain.com.crt;
    ssl_certificate_key /etc/nginx/ssl/api.yourdomain.com.key;

    # 允许上传大图 (用于 /v1/images/edits 上传原图)
    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:8080; # 网关监听端口

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 核心优化：生图大模型生成时间长，必须关闭缓冲并大幅延长超时时间至 600s
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        proxy_connect_timeout 60s;
    }
}

---

四、 Web 管理控制台与在线配置

服务启动后，在浏览器直接打开： 👉 http://<服务器IP>:<端口>/admin

• 默认管理密码：admin123（可在控制台中修改或通过环境变量 ADMIN_PASSWORD 指定）
• 支持在线热重载：
  • 上游 CPA / 大模型 Base URL、请求超时时间。
  • 存储驱动切换：RustFS / S3 / 阿里云 OSS / 腾讯云 COS / MinIO、HTTP Multipart 通用图床、纯内存 Base64 模式。
  • 内置 “自定义 Base64 实时测试上传” 功能，上传后即可即时获得云存储公网直链并一键打开验证。
  • 内置 “网关运行日志监控面板”，无需翻阅服务器控制台，在网页端一键点击即可查看最新生图与报错堆栈。
  • 修改后实时热更新至内存并持久化至 data/config.json，无需重启进程。

---

五、 API 接口对接说明

任何兼容 OpenAI 标准的客户端（LobeChat / NextChat / 业务后端）只需将 Base URL 设置为本网关地址：http://<服务器IP>:<端口>/v1

1. 文生图 (POST /v1/images/generations)

• 请求体：

  {
    "prompt": "A cute baby sea otter floating on water",
    "model": "gemini-3.1-flash-image",
    "response_format": "url"
  }

• 响应（标准 OpenAI 格式，自动转存图床/RustFS/OSS 返回直链）：

  {
    "created": 1718000000,
    "data": [
      { "url": "https://oss.wangziheng.vip/2026/09/xxxx.png" }
    ]
  }

2. 图生图 / 编辑图片 (POST /v1/images/edits)

• 支持标准 multipart/form-data 或 application/json（携带 image 字段及 prompt 修改指令）。
• 网关自动将原图转化为多模态 Vision 消息发给上游具备视觉能力的大模型，并将修改后返回的图片 Base64 转存交付。

3. 通用透明代理透传 (ANY /*)

• 访问 /v1/chat/completions、/v1/models 等非生图接口时，网关将无损原样反向代理至配置的上游服务，客户端自带的 Authorization Bearer 密钥全透明透传。

4. 健康检查探针

• GET /health 或 GET /ping ➔ 返回 HTTP 200 { "status": "ok" }。

---

六、 自动化构建与 Release 发版

本项目配置了完整的 GitHub Actions CI/CD 流水线。推送形如 v1.0.0 的 Git Tag 时，GitHub 会全自动编译全平台独立单二进制文件并发布至 Releases：

git tag v1.0.0
git push origin v1.0.0