# CX-imageWorkbench

**Repository Path**: mgdh5/cx-image-workbench

## Basic Information

- **Project Name**: CX-imageWorkbench
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cx-image-workbench

`cx-image-workbench` 是一个面向 Codex CLI 的本地图片工作台。它提供浏览器界面，接收文生图、参考图生成、单图编辑、遮罩编辑、多图融合和连续迭代任务，并把任务串行交给本机 `codex exec` 处理。

## 运行方式

1. 浏览器把 prompt 和上传文件发给本地 Node 服务。
2. 服务把 prompt、上传文件和任务状态写入运行时目录，并把受管文件统一放入项目内的 live/trash 目录。
3. 服务调用本机 `codex` CLI 执行图片生成或编辑。
4. 服务把成功结果转移到受管结果目录，再把预览和结果标签回传给前端。

相同输入图现在会按内容哈希缓存：

- 服务端只保留一份相同内容的受管 input 文件
- 同一浏览器里重复提交同一张图时，即使刷新页面，后续请求也会优先复用缓存 key，而不是重复发送整张图片

## 依赖前提

- Node.js 20+
- 本机可直接执行的 `codex` CLI
- 当前机器上已经可用的 Codex 登录态和宿主图像工具能力
- 对运行时目录有可写权限

## 默认目录

如果不传环境变量，服务会优先兼容旧工作区结构；若未发现旧结构，则退回当前项目内的运行时目录：

- `data/`：任务持久化数据
- `runtime/library/live/prompts/`：受管 prompt 目录
- `runtime/library/live/inputs/`：受管输入图目录
- `runtime/library/live/results/`：受管结果图目录
- `runtime/library/trash/`：删除任务后的受管文件回收区
- `~/.codex/generated_images/`：Codex 原始生成目录

如果项目旁边存在 `../garden-gpt-image-2/prompt/` 和 `../garden-gpt-image-2/uploads/`，服务会默认继续使用它们，以兼容你当前本地环境。

## 环境变量

服务不会自动加载 `.env`，需要你通过 shell、systemd、Docker 或进程管理器显式注入。

- `APP_NAME`：前端显示名称，默认 `CX Image Workbench`
- `HOST`：监听地址，默认 `127.0.0.1`
- `PORT`：监听端口，默认 `4318`
- `CX_ADMIN_TOKEN`：可选，设置后所有 `/api/*` 请求都必须携带 `x-cx-admin-token`
- `DATA_DIR`：任务数据目录
- `PROMPT_DIR`：prompt 落盘目录
- `UPLOAD_DIR`：上传文件目录
- `GENERATED_DIR`：Codex 生成图片目录
- `CODEX_WORKSPACE_ROOT`：执行 `codex exec` 时使用的工作目录
- `CODEX_BIN`：Codex 可执行文件名或绝对路径，默认 `codex`
- `CODEX_RELAY_URL`：可选，用于记录每个任务启动 `codex exec` 时使用的 relay/base URL；未设置时依次回退读取 `OPENAI_BASE_URL`、`OPENAI_API_BASE`

任务记录里展示的 relay/base URL 会去掉用户名、密码、query string 和 hash fragment。`CODEX_RELAY_URL` 只是工作台自己的显式记录值；`codex exec` 仍然继承当前进程环境变量，所以已有的 `OPENAI_BASE_URL` 或 `OPENAI_API_BASE` 配置不需要改名。

## 本地启动

```bash
cd cx-image-workbench
mkdir -p data runtime/prompts runtime/uploads
npm install
npm start
```

打开：

```text
http://127.0.0.1:4318
```

如果你要继续复用旧目录，也可以这样启动：

```bash
cd cx-image-workbench
PROMPT_DIR=../garden-gpt-image-2/prompt \
UPLOAD_DIR=../garden-gpt-image-2/uploads \
CODEX_WORKSPACE_ROOT=.. \
npm start
```

## 服务器部署

这个项目更适合部署在你自己可控的 Linux 服务器或工作站，因为它依赖本机 `codex` CLI 和该机器上的登录态。

一个常见部署方式：

```text
/srv/cx-image-workbench/
  cx-image-workbench/
    public/
    data/
    runtime/
```

示例启动：

```bash
cd /srv/cx-image-workbench/cx-image-workbench
HOST=127.0.0.1 \
PORT=4318 \
CX_ADMIN_TOKEN=replace-with-a-long-secret \
npm start
```

然后用 Nginx 或 Caddy 反代到公网，建议继续让 Node 服务只监听 `127.0.0.1`。

## 鉴权

项目现在内置了一个轻量级 token 鉴权。

- 未设置 `CX_ADMIN_TOKEN`：行为与本地单机版一致，不需要 token
- 设置了 `CX_ADMIN_TOKEN`：除 `/api/config` 外，其余 `/api/*` 请求都必须带 `x-cx-admin-token`
- 静态页面资源 `/`、`/index.html`、`/app.css`、`/app.js` 仍可直接访问，前端会提示输入 token

反向代理层仍然建议再加一层保护，例如 Basic Auth、VPN、IP allowlist 或 SSO。

## Docker

仓库内带了一个基础 `Dockerfile`，可用于打包这个 Web 服务本身。真实出图仍然要求容器里存在可用的 `codex` CLI，并且容器用户拥有有效登录态。

构建镜像：

```bash
docker build -t cx-image-workbench .
```

示例运行：

```bash
docker run --rm -p 4318:4318 \
  -e HOST=0.0.0.0 \
  -e PORT=4318 \
  -e CX_ADMIN_TOKEN=replace-with-a-long-secret \
  -e GENERATED_DIR=/root/.codex/generated_images \
  -v "$HOME/.codex:/root/.codex" \
  -v "$(pwd)/data:/app/data" \
  -v "$(pwd)/runtime/prompts:/app/runtime/prompts" \
  -v "$(pwd)/runtime/uploads:/app/runtime/uploads" \
  cx-image-workbench
```

如果容器里没有 `codex`，服务界面仍能启动，但生成任务会失败。

## 运行时文件

这些内容属于运行时状态，不应提交到代码仓库：

- `data/jobs.json`
- `runtime/library/live/`
- `runtime/library/trash/`
- `runtime/prompts/`
- `runtime/uploads/`
- `~/.codex/generated_images/`

仓库只保留 `data/.gitkeep` 以保留目录结构。

## 删除任务

- 已完成、失败、已跳过的任务可以删除。
- 删除只会移除任务记录，不会直接删除原始素材。
- 任务相关 prompt、输入图和结果图会被移动到 `runtime/library/trash/`。
- 正在排队或运行中的任务仍然需要先跳过或熔断，再删除记录。