批量 AI 抠图 · 部署说明(零外部依赖)

# ps 批量 AI 抠图 · 部署说明

> 适用版本：本地完全离线版（库 + 推理引擎 + AI 模型全部打包在 `vendor/`，页面零外部依赖）

> 最后更新：2026-08-04

---

## 一、部署文件清单

**必须上传（3 项）：**

| 文件/目录 | 大小 | 说明 |

|-----------|------|------|

| `index.html` | 约 30 KB | 主页面（上传区 / 参数区 / 任务队列 / 悬浮操作栏） |

| `vendor/` | 约 212 MB | 全部运行依赖：AI 库、onnxruntime-web 推理引擎、AI 模型（U²-Net）、JSZip |

| `.htaccess` | 约 0.6 KB | Apache 环境必带：`.mjs` MIME 类型 + COOP/COEP 跨域隔离头（Nginx 环境需改用配置，见第五节） |

> `vendor/imgly/model/` 约 211 MB，包含 AI 模型分块（small + medium），是体积大头，属正常。

**上传后目录结构（示例）：**

/path/to/site/

├── index.html

├── .htaccess            ← 仅 Apache 需要

└── vendor/

    ├── imgly/model/     ← AI 模型（资源清单 + 分块）

    ├── lib/             ← 抠图库

    ├── onnxruntime-web/ ← 推理引擎

    ├── jszip/           ← ZIP 打包

    └── 若干 .mjs 依赖

---

## 二、可以不上传的文件（本地保留即可）

以下文件与运行无关，**无需上传**，避免浪费空间和带宽：

| 文件 | 说明 |

|------|------|

| `background-removal-data-1.4.5/` | 原始模型下载包，`vendor/imgly/model/` 已包含其内容 |

| `ps.rar` / `p1s.rar` | 本地压缩包备份 |

| `参考.html` | 抠抠图参考页面 |

| `*.bak-*` | 历史修改备份 |

---

## 三、环境要求

1. **必须 HTTPS**（或本机 localhost）

   - 页面依赖 COEP 跨域隔离启用 WASM 多线程，这要求"安全上下文"（secure context）。

   - 纯 HTTP 线上部署会退回单线程推理，速度明显变慢，控制台出现 `numThreads ... crossOriginIsolated` 警告。

2. **必须经 HTTP(S) 访问，不能 file:// 直接打开**——浏览器会因 CORS 拒绝加载模型分块。

3. **不支持 IE**，请使用 Chrome / Edge / Firefox / Safari 等现代浏览器。

---

## 四、Apache 环境配置

Apache 环境下，随包上传的 `.htaccess` 即可生效，其内容为：

```apache

# 本地 AI 抠图工具：确保 ES 模块(.mjs)与 wasm 以正确 MIME 提供

# 浏览器对 <ｓｃｒｉｐｔ type="module"> 强制校验 JavaScript MIME，否则拒绝执行

AddType text/javascript .mjs

AddType application/javascript .mjs

AddType application/wasm .wasm

# 启用 Cross-Origin Isolation，允许 onnxruntime-web 使用多线程 WASM

# 所有子资源必须来自同域或带有 CORP 头；本页所有资源均为同域，无外部依赖

<IfModule mod_headers.c>

  Header set Cross-Origin-Opener-Policy "same-origin"

  Header set Cross-Origin-Embedder-Policy "require-corp"

</IfModule>

**需要确认的两点：**

1. **`mod_headers` 模块已启用**

   ```bash

   # Debian/Ubuntu

   sudo a2enmod headers

   sudo systemctl reload apache2

2. **目录允许 `.htaccess` 覆盖**（`AllowOverride` 不能是 `None`）：

   ```apache

   <Directory "/path/to/site">

       AllowOverride All

       Require all granted

   </Directory>

> 若无法启用 `AllowOverride`，也可直接把上述 `Header set` 与 `AddType` 写进 Apache 主配置的 `<VirtualHost>` 或 `<Directory>` 块内。

---

## 五、Nginx 环境配置

Nginx **不识别 `.htaccess`**，需在站点配置（`server` 块）中手动添加：

server {

    listen 443 ssl http2;

    server_name 你的域名;

    # HTTPS 证书配置（必须，跨域隔离需要安全上下文）

    ssl_certificate     /path/to/cert.pem;

    ssl_certificate_key /path/to/key.pem;

    root /path/to/site;

    index index.html;

    # 1) ES 模块 .mjs 必须按 JavaScript 提供，否则浏览器拒绝执行

    location ~ \.mjs$ {

        add_header Content-Type "text/javascript" always;

        try_files $uri =404;

    }

    # 2) 跨域隔离头：让 onnxruntime 多线程 WASM 生效

    add_header Cross-Origin-Opener-Policy "same-origin" always;

    add_header Cross-Origin-Embedder-Policy "require-corp" always;

    # 3) 静态资源缓存（可选，加速二次加载）

    location /vendor/ {

        add_header Cache-Control "public, max-age=31536000, immutable";

    }

    location / {

        try_files $uri $uri/ /index.html;

    }

}

**要点：**

- `.mjs` 的 `Content-Type` 必须为 `application/javascript`（或 `text/javascript`），浏览器对 ES 模块强制校验 MIME。

- COOP / COEP 头要加在**所有响应**上（`always`），包括 index.html 和 vendor 下的资源。

- 若静态资源托管在 CDN 上，CDN 需放行并透传这些响应头。

---

## 六、部署后验证

1. 打开 `https://你的域名/`，F12 → Network 面板：

   - `vendor/lib/index.mjs` → 状态 200，`Content-Type: application/javascript`

   - `vendor/imgly/model/resources.json` → 状态 200

   - 模型分块文件 → 状态 200（约 4 MB / 个）

2. F12 → Console：

   - 无 `numThreads ... crossOriginIsolated` 警告 → 跨域隔离生效

   - 无红色报错 → 依赖加载正常

3. 上传 1 张图点"开始批量抠图"，观察：

   - 首次会下载模型（small 约 44 MB / medium 约 88 MB），页面显示"正在加载 AI 抠图引擎"

   - 单张出图后卡片状态变"已完成"，可下载 / ZIP 打包

---

## 七、常见问题 FAQ

**Q1：打开页面一片空白 / 控制台报 `Failed to load module ｓｃｒｉｐｔ`**

- `.mjs` MIME 未配置（Apache 检查 `.htaccess` 是否生效；Nginx 检查 `location ~ \.mjs$`）。

- 确认是通过 `http(s)://` 访问，而不是 `file://`。

**Q2：控制台报 `numThreads is set to ... but this will not work unless crossOriginIsolated`**

- COOP / COEP 头未生效或站点不是 HTTPS。

- 按第四节 / 第五节补上头，并用 HTTPS 访问。

**Q3：处理速度慢（单张 30s+）**

- 大概率是跨域隔离没生效（退回单线程）。先按 Q2 排查。

- 确认 Chrome/Edge 里 `chrome://gpu` 的 WebGL/WebGPU 正常；CPU 机器上批量并发会自动降为 1。

**Q4：个别图有阴影 / 主体被切**

- 参数区可调：去白边（spill）默认 4，阴影残留可拉到 5；边缘收缩默认 0，深阴影可调 1~2，主体被切则调回 0。

**Q5：模型精度下拉为什么只有一项？**

- 已移除 small（极速）模型选项：小模型预测边缘粗糙、阴影更多。如需恢复，在 `index.html` 的 `<select id="model">` 内加回 `<option value="small">极速（体积小）</option>` 即可。

**Q6：212 MB 太大，能否瘦身？**

- 模型分块中 small + medium 是分开的。若确定只用高精度（medium），可参照 `vendor/imgly/model/resources.json` 确认分块归属后删除 small 相关分块；此操作风险较高，建议保留全量。

---

> 部署即交付，全部为静态文件，无需数据库、无需 PHP、无需构建，上传即用。