HivisionIDPhotos v1.3.1 Docker Compose 部署指南

目标：在 Ubuntu 24.04 服务器上用 Docker Compose 从零部署 HivisionIDPhotos v1.3.1（开源 AI 证件照制作工具）的双服务形态——Web UI（Gradio）与 API 后端（FastAPI），覆盖外部网络准备、编排文件编写、启动核验、两服务健康验证、Web 出图实测、持久化说明、升级回滚与常见问题排障。文中全部命令与回显均在真实部署环境（Ubuntu 24.04.5、Docker 29.9.2、Docker Compose v5.6.1、官方 Docker 发行 linzeyi/hivision_idphotos:v1.3.1）实测通过，取材日期 2026-10-25。项目的定位与功能介绍见本专栏介绍篇。

一、环境信息

本篇部署目标与实测环境的关键信息如下，读者按本文操作时请将路径与端口换成自己环境的取值：

操作系统：Ubuntu 24.04.5 LTS（Noble Numbat），x86_64
Docker 引擎：Docker version 29.9.2（支持 Compose v2 插件，docker compose 子命令可用，实测为 v5.6.1）
官方 Docker 发行：linzeyi/hivision_idphotos:v1.3.1（2026-10-25 实查 digest sha256:8178b9498a22a7d0cfe9e48091c2645e2def6a957bf2c6eb4ed2db3fc3529c7d，磁盘占用约 2.92GB；对应 GitHub Release v1.3.1，发布于 2025-01-21）
服务端口：Web UI 对外发布 8138（映射到服务内 7860），API 后端对外发布 8139（映射到服务内 8080）
部署目录：编排文件 docker-compose.yml 所在目录，即 compose 项目目录（本文以 /opt/hivision/ 为示例路径；实测编排的项目名为 hivision-v1.3.1-stack）
编排网络：外部网络 hivision-v1.3.1-net（需在启动前手工创建，见 4.1）

版本取证（本机实查， digest 与发行大小均为现场输出）：

docker images --digests linzeyi/hivision_idphotos

实测回显：

REPOSITORY                  TAG       DIGEST                                                                    IMAGE ID       CREATED         SIZE
linzeyi/hivision_idphotos   v1.3.1    sha256:8178b9498a22a7d0cfe9e48091c2645e2def6a957bf2c6eb4ed2db3fc3529c7d   8178b9498a22   21 months ago   2.92GB

二、部署形态说明

官方仓库为同一份官方 Docker 发行提供了两种运行入口，靠启动命令区分——这是理解编排文件里两个服务的钥匙：

服务	启动入口	服务内监听	本文对外端口	用途
`hivision-web`	`python3 -u app.py --host 0.0.0.0 --port 7860`	7860（Gradio Web UI）	8138	浏览器交互制证：上传照片→选尺寸/底色→下载标准照、高清照、六寸排版照
`hivision-api`	`python3 deploy_api.py`	8080（FastAPI）	8139	程序化调用：提供 7 个 HTTP 接口（生成证件照、添加背景色、六寸排版、人像抠图、加水印、设 KB、证件照裁切），自带交互式文档 `/docs`

取舍建议：

只想用网页做证件照：编排里保留 hivision-web 一个服务即可，hivision-api 段整段删除，不影响任何功能。
要嵌入自己的工作流/小程序后端：保留 hivision-api；两个服务互相独立，不共享任何运行时状态，同机共存没有依赖关系，仅共用同一外部网络便于统一管理。
两者都留（本文实测形态）：内存开销约 1GB 以内（实测空闲状态 web 约 600MiB、api 约 375MiB），个人服务器/NAS 完全放得下。

模型文件说明：HivisionIDPhotos 的制证能力依赖人像抠图模型权重（默认 modnet_photographic_portrait_matting.onnx，约 24.7MB）与人脸检测模型（默认 mtcnn，随项目内置）。按官方 README 的指引，源码部署时权重需放到项目 hivision/creator/weights 目录下；而本文采用的拉取官方 Docker 发行形态，默认抠图权重已内置在发行层中，无需手工下载、也无需任何目录挂载（本文实测编排无任何 volumes 配置，部署后直接出图成功）。只有选择源码构建发行（README 的 Dockerfile/compose build 方式）时，才需要先按 README 把至少一个抠图权重放到 hivision/creator/weights 下再构建。

三、前置条件

已安装 Docker 引擎与 Compose v2 插件，以下命令能正常输出版本号：

docker --version && docker compose version

实测回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

磁盘与内存余量：官方 Docker 发行约 2.92GB，建议预留 4GB 以上磁盘；两个服务空闲实测合计约 975MiB 内存，默认模型组合（MODNet + mtcnn）官方性能参考内存占用约 410MB，2GB 以上可用内存即可稳定运行。
规划两个空闲的对外端口（本文用 8138、8139），执行前先确认未被占用：

ss -ltn | grep -E ':8138|:8139' || echo "8138/8139 空闲"

部署前执行，输出 8138/8139 空闲 即可继续；若列出了 LISTEN 行，说明端口已被占用，请换端口或释放后再部署（部署成功后该命令应能看到 8138/8139 的 LISTEN 记录，见 4.4）。

模型权重无需准备：拉取官方 Docker 发行形态默认权重已内置（见第二章说明）。如后续要切换 rmbg-1.4、birefnet-v1-lite 等更大模型，再按官方 README 的模型清单单独下载，网速不佳时可前往官方提供的 SwanHub 下载地址获取。

四、部署步骤

本节按「创建外部网络 → 编写编排文件 → 启动 → 核验 → 探活」的顺序完成从零到可用。

4.1 创建外部网络

本文编排使用显式声明的外部网络 hivision-v1.3.1-net（external 方式的好处：网络生命周期独立于 compose 项目，down 不会误删，多套编排可复用）。先创建：

docker network create hivision-v1.3.1-net

命令执行成功无回显；用 docker network ls 核验：

docker network ls

实测回显（节选）：

NETWORK ID     NAME                           DRIVER    SCOPE
8eff1604949d   hivision-v1.3.1-net            bridge    local

4.2 编写编排文件

创建部署目录并写入 /opt/hivision/docker-compose.yml，内容如下（与本文实测运行文件一致，两个服务均来自同一官方 Docker 发行，靠 command 区分启动入口）：

name: hivision-v1.3.1-stack

services:
  hivision-web:
    container_name: hivision-v1.3.1-web
    image: linzeyi/hivision_idphotos:v1.3.1
    command: python3 -u app.py --host 0.0.0.0 --port 7860
    ports:
      - "8138:7860"
    networks:
      - hivision-net
    restart: unless-stopped

  hivision-api:
    container_name: hivision-v1.3.1-api
    image: linzeyi/hivision_idphotos:v1.3.1
    command: python3 deploy_api.py
    ports:
      - "8139:8080"
    networks:
      - hivision-net
    restart: unless-stopped

networks:
  hivision-net:
    external: true
    name: hivision-v1.3.1-net

编排要点解读：

两个服务、同一发行：hivision-web 与 hivision-api 的 image 完全相同，仅 command 不同——前者启动 Gradio 网页服务，后者启动 FastAPI 后端。
端口映射：8138:7860 与 8139:8080，左侧是对外发布端口（可按需修改），右侧是服务内监听端口，与第二章表格对应。
外部网络：networks.hivision-net 以 external: true 引用 4.1 创建的 hivision-v1.3.1-net；若跳过 4.1 直接启动，编排会因找不到该网络而失败。
重启策略：restart: unless-stopped，随宿主机开机自动拉起（除非手工停止）。
无任何 volumes：默认权重内置、无状态服务，故实测编排未配置挂载（详见第六章）。

4.3 启动服务

cd /opt/hivision
docker compose up -d

首次启动会先从 Docker Hub 拉取约 2.92GB 的官方 Docker 发行（国内网络拉取慢或超时时，为 Docker 引擎配置代理或加速地址后重试 docker compose pull 即可）。

4.4 核验运行状态

docker compose ps

实测回显：

NAME                  IMAGE                              COMMAND                  SERVICE        CREATED          STATUS          PORTS
hivision-v1.3.1-api   linzeyi/hivision_idphotos:v1.3.1   "python3 deploy_api.…"   hivision-api   28 minutes ago   Up 28 minutes   7860/tcp, 0.0.0.0:8139->8080/tcp, [::]:8139->8080/tcp
hivision-v1.3.1-web   linzeyi/hivision_idphotos:v1.3.1   "python3 -u app.py -…"   hivision-web   28 minutes ago   Up 28 minutes   8080/tcp, 0.0.0.0:8138->7860/tcp, [::]:8138->7860/tcp

两个服务均为 Up 状态即启动成功（CREATED/STATUS 中的时长随运行时间增长，属正常现象）。再看端口监听与 Web 服务日志：

ss -ltn | grep -E ':8138|:8139'

实测回显：

LISTEN 0      4096         0.0.0.0:8138       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8139       0.0.0.0:*
LISTEN 0      4096            [::]:8138          [::]:*
LISTEN 0      4096            [::]:8139          [::]:*

docker compose logs hivision-web

实测回显（启动段节选；出图后日志中还会追加制证时序行）：

hivision-v1.3.1-web  | * Running on local URL:  http://0.0.0.0:7860
hivision-v1.3.1-web  |
hivision-v1.3.1-web  | To create a public link, set `share=True` in `launch()`.

Running on local URL: http://0.0.0.0:7860 表示 Gradio 网页服务已在服务内 7860 端口就绪（经端口映射即宿主机 8138）。

4.5 两服务健康探活

API 服务探活——访问 FastAPI 自带的交互式文档页：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8139/docs

实测回显：

HTTP 200

再确认 API 暴露的接口清单：

curl -s http://localhost:8139/openapi.json | python3 -c "import json,sys; print('\n'.join(sorted(json.load(sys.stdin)['paths'].keys())))"

实测回显：

/add_background
/generate_layout_photos
/human_matting
/idphoto
/idphoto_crop
/set_kb
/watermark

Web UI 探活：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8138/

实测回显：

HTTP 200

两个 200 即双服务健康。浏览器访问 http://<服务器IP>:8138 进入制证网页，http://<服务器IP>:8139/docs 打开 API 调试页。

五、部署验证

5.1 Web UI 出图实测

浏览器打开 http://<服务器IP>:8138，在网页中上传一张正面人像（官方 demo 图 test0.jpg 即可），尺寸选「一寸」（295×413px），底色选蓝色，点击生成。实测成功产出标准证件照成品——人像边缘抠图干净，蓝色纯色底完整，可直接下载保存（实测产物截图见 webui_standard.png：一寸比例、蓝底、正装人像的标准照）。

与出图对应的 Web 服务日志（制证四阶段的真实时序）：

hivision-v1.3.1-web  | [1]  Start Human Matting...
hivision-v1.3.1-web  | [1]  Human Matting Time: 0.329s
hivision-v1.3.1-web  | [2]  Start Beauty...
hivision-v1.3.1-web  | [2]  Beauty Time: 0.007s
hivision-v1.3.1-web  | [3]  Start Face Detection...
hivision-v1.3.1-web  | [3]  Face Detection Time: 0.502s
hivision-v1.3.1-web  | [4]  Start Image Post-Adjustment...
hivision-v1.3.1-web  | [4]  Image Post-Adjustment Time: 0.003s
hivision-v1.3.1-web  | [Total]  Total Time: 0.841s

四个阶段即「人像抠图 → 美颜 → 人脸检测 → 图像后处理」，纯 CPU 推理单张全程不到 1 秒，说明内置默认模型权重加载正常。

5.2 API 出图实测

对 8139 端口的 /idphoto 接口发一次真实请求（上传同一张测试照），返回 status: true 与 base64 编码的标准/高清两张证件照，服务日志同时打印制证时序：

hivision-v1.3.1-api  | [1]  Start Human Matting...
hivision-v1.3.1-api  | [1]  Human Matting Time: 0.300s
hivision-v1.3.1-api  | [2]  Start Beauty...
hivision-v1.3.1-api  | [3]  Start Face Detection...
hivision-v1.3.1-api  | [4]  Start Image Post-Adjustment...
hivision-v1.3.1-api  | [Total]  Total Time: 0.321s
hivision-v1.3.1-api  | INFO:     10.89.57.1:47014 - "POST /idphoto HTTP/1.1" 200 OK

POST /idphoto 200 OK 即 API 链路完整可用。各接口的参数与 cURL/Python 请求示例以官方 API 文档为准（见参考链接）。

六、数据持久化与备份

这套部署没有需要维护的状态数据目录——实测 docker inspect 两个服务的挂载列表均为空（[]）：

模型权重：内置在官方 Docker 发行层中，随发行一起升级，无需单独备份。
制证产物：服务本身不落盘，标准照/高清照/排版照以 base64 经 HTTP 返回，由浏览器或调用方保存，服务器上不会积累照片文件。
用户数据：工具无账号体系、无数据库，不存在配置漂移。

因此备份与迁移的对象只有两样：编排文件与外部网络。迁移到新服务器时按顺序执行：

# 1. 打包编排文件带走（在本机执行）
tar czf hivision-compose.tgz -C /opt hivision/docker-compose.yml
# 2. 新机解包到 /opt/hivision 后，创建同名外部网络
docker network create hivision-v1.3.1-net
# 3. 启动（自动重新拉取发行）
cd /opt/hivision && docker compose up -d

七、升级与回滚

升级：编排中版本由 image 的 tag 锁定为 v1.3.1。官方发布新版本后，把两个服务的 tag 改成目标版本号，然后：

cd /opt/hivision
docker compose pull && docker compose up -d

升级不涉及数据迁移（无状态服务），新旧发行仅共存于磁盘，回滚只需改回 tag 再执行同样两条命令。

生产环境建议用 digest 锁定：tag 可能被官方重新指向新构建，digest 则内容寻址、绝对不可变。本文实测 v1.3.1 的 digest 为 sha256:8178b9498a22a7d0cfe9e48091c2645e2def6a957bf2c6eb4ed2db3fc3529c7d，把两个服务的 image 行写成 linzeyi/hivision_idphotos@sha256:8178b949…（digest 完整值见第一章取证）即可将环境钉死在本次验证过的构建上。

⚠️ 注意：同一发行的两个服务（web/api）必须使用同一个版本（tag 或 digest），混用版本可能导致网页与接口的制证行为不一致。

八、常见问题排障

Q1：启动时报找不到外部网络 hivision-v1.3.1-net？ 现象：docker compose up -d 失败，提示无法找到 external 声明的网络。原因：跳过了 4.1 或网络被手工删除。处置：docker network create hivision-v1.3.1-net 后重新 docker compose up -d。

Q2：端口 8138/8139 被占用，服务起不来？ 现象：启动失败或浏览器无法访问。原因：宿主机上已有其他进程占用了发布端口。处置：ss -ltn | grep -E ':8138|:8139' 找到占用方，停掉它，或直接改编排文件 ports 左侧端口（如 "9138:7860"）后 docker compose up -d。

Q3：调用 /idphoto 接口返回 Internal Server Error（HTTP 500）？ 现象：对无正脸的照片请求生成证件照，接口返回 500；服务日志中出现 mtcnn 人脸检测环节的 ValueError: need at least one array to concatenate 堆栈（本文实测复现）。原因：输入照片中检测不到人脸，默认 mtcnn 模型在无脸输入下直接抛出异常。处置：换清晰正面人像重试；若业务上必须处理无脸图，可改调 /human_matting（人像抠图）接口绕过人脸检测环节。

Q4：内存不足或推理变慢？ 现象：服务被系统 OOM 杀掉，或大尺寸照片推理明显变慢。原因：默认模型组合内存开销不大（官方性能参考约 410MB，本文实测两服务空闲合计约 975MiB），但若在环境变量中设置 RUN_MODE=beast（野兽模式：模型不释放内存换更快二次推理），官方建议 16GB 以上内存；切换 birefnet-v1-lite 抠图模型时官方性能参考内存占用达 6.2GB。处置：小内存环境不设 RUN_MODE、继续用默认 MODNet + mtcnn 组合即可。

Q5：首次启动卡在拉取官方 Docker 发行？ 现象：docker compose up -d 长时间停在分层下载。原因：约 2.92GB 的发行体积叠加国内到 Docker Hub 的网络状况。处置：为 Docker 引擎配置代理或加速地址后重试；下载完成后升级/重启均不会重复拉取同 digest 的发行。

Q6：想要更换或新增模型权重，往哪放？ 本文的拉取形态权重内置、无挂载点，不能直接往里放文件。如需使用 hivision_modnet、rmbg-1.4、birefnet-v1-lite 等其他抠图模型或 retinaface-resnet50 人脸检测模型，按官方 README 走源码构建形态：把权重放到项目 hivision/creator/weights（RetinaFace 放 hivision/creator/retinaface/weights）后再构建自己的发行版本，并在编排中为对应服务增加 volumes 挂载。

九、参考链接

HivisionIDPhotos 官方仓库（含 README 的 Docker 部署章节与模型下载指引）：https://github.com/Zeyi-Lin/HivisionIDPhotos （查询日期 2026-10-25）
官方 README（中文，Docker 部署章节）：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/README.md （查询日期 2026-10-25）
v1.3.1 Release 页面：https://github.com/Zeyi-Lin/HivisionIDPhotos/releases/tag/v1.3.1 （查询日期 2026-10-25）
官方 Docker 发行页（linzeyi/hivision_idphotos）：https://hub.docker.com/r/linzeyi/hivision_idphotos （查询日期 2026-10-25）
官方 API 文档（接口参数与请求示例）：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/docs/api_CN.md （查询日期 2026-10-25）
本站相关文档：《HivisionIDPhotos 介绍与选型指南》（见本专栏介绍篇）