Image Studio 是一个依赖极少的本地 / 自托管 Web 工作站，用于管理 OpenAI-compatible 图片生成与对话接口、提交图片生成任务、管理用户额度和本地图库。当前实现基于 Node.js 原生 HTTP、SQLite、浏览器端 ES Modules 与本地文件存储，默认运行在 http://localhost:8787。

当前产品说明见 docs/PRODUCT_CURRENT.md，未来商业化演进方案见 docs/PRODUCT_ROADMAP.md；生产部署、反向代理、备份恢复和容量规划见 docs/DEPLOYMENT.md；系统默认 API Key 的当前存储决策见 docs/API_KEY_STORAGE_DECISION.md。

本项目采用 MIT License 完整开源，感谢 LINUX DO 社区对开源项目推广与交流的支持。

• 运行形态：单进程 Node.js 服务 + SQLite + generated/ 本地持久化目录。
• 用户模型：支持注册、登录、session、普通用户与管理员角色。
• 管理能力：管理员可管理用户、额度、生成队列、客户端日志、系统默认接口和图库。
• 生成能力：支持异步入队提交、SSE/队列进度、参考图编辑、多图拆分、任务重试/取消。
• 提示词能力：支持 Prompt Builder、历史、提示词广场、示例图上传与漫画分镜工作流。
• 部署定位：适合个人、本地或小团队自托管；如作为公网 SaaS，需要先升级密钥存储、对象存储、审计和多租户边界。

cp .env.example .env
# 按需修改 .env；生产空库首次初始化请设置 ADMIN_BOOTSTRAP_TOKEN
npm start       # 自动加载 .env 后启动，默认 http://localhost:8787
npm test        # Node 原生 test runner，零外部依赖

npm start 会在启动前自动读取项目根目录的 .env（不覆盖当前 shell 已设置的同名环境变量）；docker compose 也会继续按 Compose 规则读取 .env。

要求：

• Node.js >=22.5.0
• 启动需带 --experimental-sqlite（npm start 已配置）
• 项目无第三方运行依赖，主要使用内置 fetch / http / node:test / node:sqlite

启动脚本会先做运行时预检：确认 Node 版本达到 node:sqlite 的最低要求，并在导入服务前验证 node:sqlite 可用；CI 持续覆盖 Node 22.x，使用其他 Node 主版本部署前请先运行 npm test 验证兼容性。

本仓库没有独立构建步骤。除非任务明确要求，不需要运行构建/编译命令。

首次管理员初始化按运行环境区分：

• 本地 / 开发环境（NODE_ENV 不是 production）仍保留低门槛体验：空库首次注册会自动创建管理员账号。
• 生产环境（NODE_ENV=production）默认要求设置 ADMIN_BOOTSTRAP_TOKEN，并在注册页填写该令牌才能创建首个管理员，避免公网首启窗口被抢占。
• 如果确认部署只暴露在可信内网，且需要保留旧行为，可显式设置 ALLOW_FIRST_ADMIN_WITHOUT_TOKEN=1；公网部署不建议启用。

为兼容旧部署，如果数据库里已有普通用户但没有活跃管理员，仍可设置 ADMIN_BOOTSTRAP_TOKEN 并在注册页填写该令牌来初始化管理员。

注册默认关闭：

REGISTRATION_MODE=closed
ADMIN_BOOTSTRAP_TOKEN=
ALLOW_FIRST_ADMIN_WITHOUT_TOKEN=0

可选注册模式：

• REGISTRATION_MODE=closed：关闭公开注册；本地 / 开发空库首个注册账号仍可自动成为 admin，生产空库首个管理员需 ADMIN_BOOTSTRAP_TOKEN（除非显式设置 ALLOW_FIRST_ADMIN_WITHOUT_TOKEN=1）。
• REGISTRATION_MODE=invite：自助注册必须填写 REGISTRATION_INVITE_CODE 或 REGISTRATION_INVITE_CODES。
• REGISTRATION_MODE=open：允许公开注册，但仍启用 IP 限频、邮箱域策略和蜜罐字段。

防刷相关：

• REGISTRATION_IP_MAX_PER_10MIN / REGISTRATION_IP_MAX_PER_DAY：注册 IP 限频。
• SIGNUP_IP_DAILY_LIMIT / SIGNUP_IP_MONTHLY_LIMIT：同一注册 IP 下普通账号共享系统默认接口额度池。
• REGISTRATION_EMAIL_DOMAIN_ALLOWLIST / REGISTRATION_EMAIL_DOMAIN_BLOCKLIST：邮箱域名放行 / 拒绝。
• LOGIN_IP_RATE_LIMIT_MAX_PER_MINUTE / LOGIN_ACCOUNT_RATE_LIMIT_MAX_PER_MINUTE / LOGIN_PAIR_RATE_LIMIT_MAX_PER_MINUTE：登录防爆破。
• 密码策略：最小 8 位、拒绝常见弱密码、拒绝包含用户名 / 邮箱本地部分，改密时不能复用原密码。
• TRUST_PROXY=1 仅应在可信反向代理会清洗转发头时启用，并用 TRUST_PROXY_ALLOWED_IPS 限定直连代理来源。

• 模型、prompt、size、quality、output format、n 参数。
• Prompt 草稿和生成参数持久化，刷新后可恢复。
• Prompt Assist：调用对话接口优化提示词。
• 手动提示词 / 优化后提示词切换。
• 参考图上传或从图库选择，支持图片编辑场景。
• 生成任务进入队列，支持进度展示、取消、重试和结果保留。
• 生成成功后自动保存到当前用户图库 generated/users/<uid>/images，元数据写入 SQLite。

• 输入故事梗概，按页数上限自动决定实际分镜页数，并规划每页分镜格数与页面内容。
• 内置彩色条漫、韩漫、黑白日漫、水墨国风、美漫动作等风格模板。
• 分镜结果可人工调整每页格数、每页内容和生图提示词，再逐页/逐格提交图片生成任务。
• 生成结果可进入图库，并可把分镜提示词保存到提示词历史。

• Prompt Builder：按主体、风格、构图、光线、配色、文字、负面提示词结构化拼装。
• Prompt 历史：保存、固定、搜索、导出、复用。
• Prompt Square：浏览公开提示词，按时间范围 / 标签筛选，复制或一键使用。
• 用户可从历史提示词发布到广场，也可删除自己发布的条目。
• 示例图上传：支持 PNG / JPEG / WebP，复用用户存储配额和路径防护；外部预览图仅保留无凭据的 HTTPS URL。

• “我的图库 / 公开图库”切换。
• 用户可公开或取消公开自己的图片。
• 公开图库支持点赞；默认每个用户每日最多点赞 10 次，可通过 PUBLIC_GALLERY_DAILY_LIKE_LIMIT 调整。
• 支持刷新、打开原图、下载和删除自己的图片。
• 管理员可查看图库统计、筛选、批量删除和扫描孤儿文件。

• 用户侧支持本地接口配置：生图接口与对话接口分别填写 Base URL、API Key、默认模型。
• API Key 不持久化到浏览器 localStorage；队列任务只在当前 Node 进程内临时持有个人 Key。
• 管理员可配置系统默认接口，普通用户可继承默认接口使用。
• 连通性测试调用各自上游 /v1/models，返回模型数量、模型 ID 摘要、耗时或错误详情。

• 浏览器本地保留最近 300 条日志。
• 前端日志可上报到服务端，管理员可在“客户端详细日志”中查看；日志面板提供“服务端同步”开关，关闭后新日志只保留在当前浏览器，并清空待同步队列。
• 上报内容包含脱敏后的消息、meta、trace id，以及页面 URL、User-Agent、语言、窗口尺寸等诊断上下文。
• 支持等级筛选、关键词搜索、导出 JSON、清空和复制单条 JSON。
• API Key、Authorization、Cookie 等敏感字段会脱敏。

仅管理员可见，包含：

• 用户管理：创建、编辑、禁用、删除用户，查看用户详情、审计、任务和客户端日志。
• 额度管理：全局默认额度、单用户额度覆盖、批量编辑、重置今日 / 本月用量；系统默认接口调用会计入日/月次数，并单独展示提示词优化次数。
• 队列调度：查看所有生成任务，调整队列设置、取消任务、修改优先级。
• 客户端日志：查看前端上报的详细日志。
• 接口管理：配置系统默认生图 / 对话接口并测试连通性。
• 图库管理：统计、筛选、批量删除和孤儿文件扫描。

• OpenAI 官方：https://api.openai.com
• 兼容网关：填根地址或带 /v1 均可；服务端会按用途规范化为 /v1/images/generations、/v1/chat/completions 或 /v1/models。
• 生产安全默认值：上游必须是 HTTPS，并阻止 localhost、私网、link-local、metadata 类地址。
• 仅隔离开发环境可显式设置 ALLOW_INSECURE_UPSTREAMS=1、ALLOW_PRIVATE_UPSTREAMS=1 放开限制。

server.js                 # HTTP server、session、CSRF、路由分发、静态文件
middleware/
  guard.js                # 鉴权、管理员权限、CSRF
  session.js              # session cookie 挂载
routes/
  auth.js                 # /api/auth/* 注册、登录、退出、当前用户
  users.js                # /api/users* 管理员用户管理
  profile.js              # /api/profile 当前用户资料与密码
  quota.js                # /api/quota/me 与 /api/admin/quota/*
  interfaces.js           # /api/interfaces/default 与 /api/admin/interfaces/default
  generate.js             # /api/generate、/api/generate/stream、生成配置
  jobs.js                 # /api/jobs* 与 /api/admin/jobs* 队列、SSE、取消、重试
  chat.js                 # /api/chat Prompt Assist / 对话代理
  gallery.js              # /api/gallery 当前用户与公开图库
  admin-gallery.js        # /api/admin/gallery* 管理员图库管理
  prompt-square.js        # /api/prompt-square 提示词广场
  prompt-examples.js      # /api/prompt-examples 示例图上传
  client-logs.js          # /api/client-logs 与 /api/admin/client-logs
  test-profile.js         # /api/test-profile 个人接口探活
  static.js               # public、/shared、/gallery-files、/prompt-example-files
services/
  db.js                   # SQLite schema、迁移、表访问封装
  auth.js                 # 密码哈希、登录、注册、session
  registration-guard.js   # 注册模式、邀请码、IP 限频、邮箱域策略
  quota.js                # 默认额度、用户额度、用量、并发槽位
  job-queue.js            # 持久化生成队列、SSE 订阅、重试/取消
  image-generation.js     # 生成任务准备、上游调用与队列结果封装
  upstream.js             # URL 规范化、安全校验、上游请求
  reference-images.js     # 参考图上传、校验、临时文件
  gallery-store.js        # 图片保存、公开图库、点赞、统计、清理
  prompt-example-images.js# 提示词示例图存储
  interface-defaults.js   # 系统默认接口配置
  client-logs.js          # 前端日志入库、查询、脱敏
  maintenance.js          # session / 日志 / 用量生命周期清理
utils/
  config.js, http.js, logger.js, mask.js, request.js, request-context.js, sse.js
shared/
  constants.js            # 前后端共享尺寸、质量、模型等常量
  comic-workflow.js       # 漫画分镜与风格模板
  redaction.js            # 前后端共享脱敏规则
public/
  index.html, login.html, styles.css, app.js, favicon.svg
  modules/                # auth、nav、studio、comic、prompts、gallery、jobs、users 等前端模块
generated/                # 运行时数据：SQLite、WAL、用户图片、临时参考图；已 gitignore
test/                     # node:test 用例
docs/                     # 产品、安全与决策文档

所有 /api/* 非 GET 请求都需要 CSRF 保护：X-Requested-With: fetch，且 Origin / Referer 必须同源。已登录 session 的非安全方法还需要携带 /api/auth/me、登录或注册响应返回的 csrfToken（X-CSRF-Token）。除 /api/auth/* 外，业务接口都要求已登录。

更完整的生产部署、反向代理、升级和回滚说明见 docs/DEPLOYMENT.md。

项目提供 Dockerfile、.dockerignore、docker-compose.yml 与 .env.example。运行时数据写入容器内 /app/generated，compose 默认使用命名卷 image-studio-generated 持久化 SQLite 数据库、WAL 文件和生成图片。

cp .env.example .env
# 按需修改 .env；生产空库首次初始化请设置 ADMIN_BOOTSTRAP_TOKEN
# 由部署者按需构建/启动镜像：docker compose up -d --build

访问：

http://localhost:8787

.env.example 默认 NODE_ENV=development 以支持 HTTP 直连；如果放到 HTTPS 反向代理后面，请设置 NODE_ENV=production，或显式设置 SESSION_COOKIE_SECURE=1，以便 session cookie 带 Secure。

健康检查：

GET /healthz

运行态数据集中在 generated/，包含 SQLite 数据库、WAL/SHM、用户图片、Prompt 示例图和临时参考图。备份/恢复前建议先停止应用，避免复制到写入中的 SQLite/WAL 状态。

# 备份 generated/ 到 backups/generated/image-studio-generated-<timestamp>/
npm run backup:generated

# 指定备份目录
npm run backup:generated -- --output /path/to/backups

# 恢复指定快照；恢复前会先为当前 generated/ 自动创建 pre-restore 备份
npm run restore:generated -- /path/to/backups/image-studio-generated-2026-06-09T09-00-00-000Z --yes

恢复已加密的系统默认 API Key 时，必须同时恢复原来的 IMAGE_STUDIO_SECRET_KEY；备份目录也应按敏感数据保护，并保持在 Git 仓库外（默认 backups/ 已被忽略）。

系统配置（system_settings，例如系统默认接口、额度默认值、队列设置、注册策略）也可以单独导出/导入，便于审计、迁移或回滚：

# 默认导出脱敏版本，适合审计和变更评审，不可直接导入
npm run config:export

# 生成可导入的完整配置导出；文件包含系统默认 API Key/密文等敏感配置，必须按备份保护
npm run config:export -- --include-secrets --output backups/system-config/prod-config.json

# 导入完整配置；--replace 会先清空现有 system_settings，省略则按 key 覆盖/合并
npm run config:import -- backups/system-config/prod-config.json --yes --replace

常用变量见 .env.example，下表按用途归类。留空或非法值通常会回退到代码默认值；部分限额变量支持 0 / disabled 表示关闭。

• generated/ 是敏感运行时目录，包含 SQLite 数据库、WAL、用户图片、示例图和临时参考图；不要提交到 Git。
• 系统默认 API Key 设置 IMAGE_STUDIO_SECRET_KEY 后会加密存入 SQLite；生产环境未配置主密钥时默认拒绝保存系统 Key（除非显式 ALLOW_PLAINTEXT_SYSTEM_KEYS=1）；详见 docs/API_KEY_STORAGE_DECISION.md。
• 个人接口 API Key 不写入 localStorage；队列任务只在当前 Node 进程内临时持有。
• 上游请求默认只允许 HTTPS + 公网地址，并对 DNS rebinding / TOCTOU 做防护。
• 头像 URL 仅接受无凭据的 HTTPS 地址；外部图片渲染默认不发送 Referer。
• 静态文件、图库文件和示例图文件走路径防护，避免越权读取。
• Docker compose 默认只读根文件系统，并仅持久化 /app/generated。

更多安全说明见 SECURITY.md。

npm test

测试使用 node:test，覆盖 auth、注册防刷、quota、job queue、gallery、prompt square、prompt 示例图、HTTP 边界、上游 URL 安全、日志脱敏、SQLite 生命周期等核心路径。

欢迎提交 Issue 和 Pull Request。参与前请阅读 CONTRIBUTING.md，并注意不要提交 .env、generated/、真实 API Key、数据库、WAL、生成图片或用户数据。

感谢 LINUX DO 社区对开源项目推广、交流与反馈的支持。

MIT. See LICENSE。