HivisionIDPhotos 证件照工具：Docker 一条命令部署，API 五秒出片自动排版

一条 Docker 命令在自己机器上跑证件照服务：换底色、标准尺寸、六寸排版一次出齐，实测 API 全链路半秒级，照片全程不出本机。

下周要办入职，人事在群里发通知：交一张白底证件照，穿深色衣服，露耳朵。

你家附近那家快照店，最便宜的一套 35 块，拍完等半小时取片。赶上急用，只能加钱。更常见的情况是：手里其实已经有几张拍得不错的照片，就是背景不对、尺寸不对，为这个重新去拍一套，多少有点冤。

我这台 Mac mini 上现在跑着一个小工具，把照片丢进网页，点一下按钮，一寸白底的标准照、高清版、还能直接排版成六寸相纸，整个过程 5 秒钟。照片全程没离开过我自己的电脑。

它叫 HivisionIDPhotos，GitHub 上的开源项目，两万一千多颗星。

这项目是什么来头

HivisionIDPhotos 是一个 AI 证件照制作工具，作者是浙江大学的团队，2023 年 6 月开源，Apache 2.0 协议，商用没有障碍。

它干的事情一句话能说完：用人像抠图模型把你的照片从背景里剥出来，再按标准尺寸和底色重新合成证件照。听起来不复杂，但证件照对人脸位置、头顶留白、耳部露出这些细节有硬性要求，这个项目内置了人脸检测来做自动对齐，成片直接能用。

图注：官方演示图——上传照片后生成标准照、高清照和排版照

热度不需要怀疑。两万一千多颗星、2500 多次 fork，Docker Hub 上的镜像拉取量很大，社区里还有人给它做了 ComfyUI 工作流、微信小程序、NAS 部署教程这些衍生品。最近一次代码提交是今年 7 月，v1.3.1 发布于 2025 年 1 月，模型和核心功能已经很稳定，属于「功能做完了、维护没停」的状态。

它支持两种用法：不想动手的直接开网页用（Hugging Face 上有免费演示），想自己部署的一条 Docker 命令就能跑起来。

最打动我的三个地方

一是快，而且不挑设备。 官方给的参考数据是 MODNet 模型加 CPU 推理单张 0.2 秒左右。我实测 API 全链路（上传原图到拿到结果）三次分别是 465、384、412 毫秒，加上网络传输也就是半秒的事。整个推理纯 CPU 就能跑，没有显卡也能用，一台家里的 NAS、一个树莓派级别的盒子都带得动。

二是尺寸库全，还能自定义。 内置了从一寸、二寸到签证尺寸的常用规格，一寸 413×295 像素、二寸 626×413，美签、日签这类特殊规格也在列表里。不在列表里的可以按像素或毫米自定义。换底色就更自由了，红白蓝是基础操作，还支持「美式证件照」这种带渐变光影的底，以及任意 HEX 色值。

三是它有 API，能接进自己的东西。 这是网页工具做不到的：它自带 FastAPI 后端，端口一开，任何程序都能调。我家里有个自动化的场景是给老人办理各类业务时常要交电子照，以后可以直接在流程里调一次接口，不用再手动开网页传照片。

图注：API 返回的标准一寸照，白底 413×295

我实际装了一遍

环境是 Mac mini M4（arm64），Docker 29.4.0。整个过程 10 分钟，其中 8 分钟在下载。

第一步，拉镜像（1.93 GB，包含运行环境，多架构支持 amd64 和 arm64）：

docker pull linzeyi/hivision_idphotos:latest

第二步，下载抠图模型权重。镜像里不带模型，需要自己挂载进去。轻量的 MODNet 只有 24.7 MB：

mkdir -p weights
curl -L "https://github.com/Zeyi-Lin/HivisionIDPhotos/releases/download/pretrained-model/hivision_modnet.onnx" \
  -o weights/hivision_modnet.onnx

第三步，写一个 docker-compose.yml：

services:
  hivision:
    image: linzeyi/hivision_idphotos:latest
    container_name: hivision-idphotos
    ports:
      - "7860:7860"
    volumes:
      - ./weights/hivision_modnet.onnx:/app/hivision/creator/weights/hivision_modnet.onnx
    environment:
      - DEFAULT_LANG=zh
    restart: unless-stopped

第四步，启动并打开网页：

docker compose up -d
# 浏览器打开 http://localhost:7860

界面就是下面这样，左边传图选参数，右边出结果。默认语言已经是中文，人脸检测模型默认用 retinaface（比 MTCNN 精度高，CPU 上慢一点但在可接受范围）。

图注：Gradio 网页界面，默认中文，左侧参数右侧结果

资源占用实测：空载时容器 172 MB 内存，跑过一轮推理后升到 945 MB 左右（模型加载进了内存），之后保持稳定。对一台 NAS 来说都在轻松驾驭的范围。

上手实测：从随手拍到能用的一寸照

我找了一张日常拍的人像照（灰色大理石背景、穿白T恤，就是那种「不能用但也不想重拍」的照片），传进网页，保持默认的一寸规格和蓝色底，点「开始制作」。

约 25 秒后（包含模型首次加载），右侧出来了三样东西：标准一寸照、高清版、以及一张六寸相纸的排版照。人脸位置自动对齐，头顶留白符合规格，头发丝的抠图边缘干净，没有白边或者碎发残留。

图注：上传照片后的生成结果——标准照、高清照、六寸排版照一次出齐

再试了「打印排版」选项卡里的六寸相纸，选好后重新生成，出来的就是一张可以直接拿去照相馆冲印的 6 寸照片，一版 8 张一寸照，冲印费按相纸算，几块钱。

图注：打印排版选项卡，支持六寸、五寸、A4、3R、4R

API 那边也跑通了一次完整链路。起一个 API 容器（同一镜像换个启动命令）：

services:
  hivision-api:
    image: linzeyi/hivision_idphotos:latest
    container_name: hivision-api
    ports:
      - "8081:8080"
    volumes:
      - ./weights/hivision_modnet.onnx:/app/hivision/creator/weights/hivision_modnet.onnx
    command: python3 deploy_api.py
    restart: unless-stopped

用 curl 调 /idphoto 接口，传原图和目标尺寸，返回里带标准照和高清照的 base64；把标准照再喂给 /add_background 换成纯白底；最后调 /generate_layout_photos 排成六寸版。三个接口串起来，就是一条完整的「照片进、冲印版出」的流水线。

有一个坑值得提前说：/generate_layout_photos 这个接口的入参必须是 4 通道的透明 PNG（就是抠图后的原始输出），我一开始把换好底的 JPG 传进去，直接 500 报错。返回的图片字段都带 data:image/png;base64, 这样的前缀，落盘前记得先去掉。

排版照的成品长这样：

图注：API 生成的六寸排版照，1795×1205，直接可冲印

美颜功能我也试了，美白强度拉到 8，出片后脸部明显提亮，效果自然。还有个「智能换正装」在官方路线图里标注 waiting，还没上线，正装照目前还得上照相馆。

谁适合上，谁先别急

适合	不适合
家里有 NAS 或常开电脑，偶尔要交电子证件照	一年用不了两次、也不想折腾任何部署的人
全家人有多样的照片需求（签证、考试报名、简历）	需要正式精修、着装改造的商业级拍摄
有自动化场景，想把证件照能力接进自己的流程	只想要个手机 App 直接拍的（它没有移动端 App）
在意隐私，不想把人脸照片传给第三方平台	对抠图边缘有极致要求的专业场景（建议上 birefnet 模型）

几个不能跳过的坑

一是默认模型和顶配模型差距很大。 默认的 MODNet 24.7 MB，速度快、边缘尚可，但遇到碎发、毛绒衣物会糊。项目支持换成 birefnet-v1-lite（224 MB），分割精度是最好的，代价是内存占用从 400 MB 级别涨到 6.2 GB，推理从 0.2 秒涨到 7 秒。16 GB 内存以下的机器别碰这个组合。

二是权重文件不放在镜像里，升级时要重新确认挂载。 官方镜像设计成「运行环境自带、模型外挂」，好处是换模型不用重拉镜像，坏处是有些人 pull 新镜像后忘了挂载权重，容器能启动但一推理就报错。记得核对 weights 目录的挂载路径。

三是 retinaface 人脸检测模型需要单独下载。 默认带的 MTCNN 检测精度一般，遇到侧脸或光线差的照片会检测失败。想要更稳的检测效果，要从项目 Release 里额外下载 retinaface-resnet50.onnx（约 110 MB）放到指定目录。下载源在 GitHub，国内网络环境可能需要代理。

四是它不修照片内容。 背景换得了，衣服换不了（功能没上线），闭眼、戴眼镜反光、表情这类问题它管不了，只管「把这张照片变成合规的证件照格式」。照片本身质量太差的话，神仙也救不回来。

五是 API 服务的并发能力有限。 单容器单模型，多张照片同时提交会排队。家庭用完全够，想对外提供服务的话要自己加队列或者起多实例。

总结与行动建议

证件照是一个低频但刚需的东西，每逢办证、入职、考试报名，它就跳出来一次。HivisionIDPhotos 把这个需求搬到了自己家里：不用下载 App、不用注册、不用把人脸照片交给哪个小程序，一条 Docker 命令就能在自己机器上跑一个证件照服务，5 秒出片，还能排版冲印。

• 只想临时用一次：直接开 Hugging Face 上的官方演示页，传照片就能用，什么都不用装。
• 已有 NAS：按上面的 compose 文件部署，挂载好模型权重，全家人的证件照需求一次解决。
• 有自动化需求：起 API 容器，三个接口串起来就是完整流水线，注意排版接口只吃透明 PNG。

参考资料

• 项目仓库：https://github.com/Zeyi-Lin/HivisionIDPhotos
• Apache 2.0 协议：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/LICENSE
• 在线演示（Hugging Face）：https://huggingface.co/spaces/TheEeeeLin/HivisionIDPhotos
• Docker 镜像：https://hub.docker.com/r/linzeyi/hivision_idphotos
• API 文档：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/docs/api_CN.md