# Docker 部署 (/zh/guide/docker)



## Docker Hub 一键运行 [#docker-hub-一键运行]

镜像发布后使用多架构 manifest，覆盖 `linux/amd64` 和 `linux/arm64`:

```bash
docker run -d \
  --name flyfish-viewer \
  --restart unless-stopped \
  -p 8080:80 \
  flyfishdev/file-viewer:latest
```

打开:

* 主预览: `http://localhost:8080/`
* iframe 嵌入: `http://localhost:8080/iframe.html?url=/example/word.docx`
* 文档比对: `http://localhost:8080/compare.html`
* 健康检查: `http://localhost:8080/healthz`

如果你希望始终使用最新稳定版本:

```bash
docker run -d \
  --name flyfish-viewer \
  --restart unless-stopped \
  -p 8080:80 \
  flyfishdev/file-viewer:latest
```

## Docker Compose [#docker-compose]

```yaml
services:
  flyfish-viewer:
    image: flyfishdev/file-viewer:latest
    container_name: flyfish-viewer
    restart: unless-stopped
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1/healthz"]
      interval: 30s
      timeout: 3s
      retries: 3
```

启动:

```bash
docker compose up -d
```

## 本地构建镜像 [#本地构建镜像]

源码仓库内提供标准 `Dockerfile`。本地只构建当前 CPU 架构并加载到 Docker:

```bash
pnpm docker:build
```

默认镜像名是 `flyfishdev/file-viewer`，标签为当前 `package.json` 版本和 `latest`。如需改成自己的命名空间:

```bash
DOCKER_IMAGE=your-org/file-viewer pnpm docker:build
```

本地运行:

```bash
docker run --rm -p 8080:80 flyfishdev/file-viewer:latest
```

## 通过 Docker Hub API 创建仓库 [#通过-docker-hub-api-创建仓库]

发布前先准备 Docker Hub Personal Access Token。仓库创建使用 Docker Hub API，镜像上传使用 Docker Registry 推送链路:

```bash
DOCKER_IMAGE=flyfishdev/file-viewer \
DOCKERHUB_USERNAME=your-dockerhub-user \
DOCKERHUB_TOKEN=dckr_pat_xxx \
pnpm docker:repo:create
```

脚本会先检查目标仓库是否存在；如果不存在，会调用 Docker Hub API 创建公开仓库。

## 多架构推送到 Docker Hub [#多架构推送到-docker-hub]

仓库创建完成后登录 Docker Hub，并确认当前账号对目标 namespace 有推送权限。如果使用自己的命名空间，请把 `DOCKER_IMAGE` 改成对应仓库名:

```bash
docker login
```

推送 `linux/amd64` 和 `linux/arm64`:

```bash
DOCKER_IMAGE=flyfishdev/file-viewer pnpm docker:publish
```

脚本默认推送稳定入口标签:

* `flyfishdev/file-viewer:latest`

如需覆盖平台或同时推送明确版本号，可以显式传入标签:

```bash
DOCKER_IMAGE=flyfishdev/file-viewer \
DOCKER_PLATFORMS=linux/amd64,linux/arm64 \
DOCKER_TAGS=2.x.x,latest \
pnpm docker:publish
```

## 镜像内容 [#镜像内容]

Docker 镜像只包含构建后的静态产物，不携带源码工作区:

* `/usr/share/nginx/html/index.html`: 主预览入口
* `/usr/share/nginx/html/iframe.html`: 无 Demo 外壳的 iframe 嵌入入口，兼容 `?url=` 与 `postMessage(Blob)`
* `/usr/share/nginx/html/compare.html`: 文档比对入口
* `/usr/share/nginx/html/assets/*`: Vite hash 资源
* `/usr/share/nginx/html/example/*`: 示例文件
* `/usr/share/nginx/html/vendor/*`: Worker / WASM 等静态资源

nginx 配置会对 HTML 使用 `max-age=0, must-revalidate`，对 hash 资源和 vendor 资源使用长缓存，避免旧入口页引用已经不存在的异步 chunk。

## 反向代理建议 [#反向代理建议]

如果容器前面还有网关或统一域名，建议保持以下路径不被重写:

* `/`
* `/iframe.html`
* `/compare.html`
* `/assets/*`
* `/vendor/*`
* `/example/*`

示例文件、WASM 和 Worker 都是静态资源；如果网关把缺失的 `.js` 或 `.wasm` 回退成 HTML，浏览器会触发 MIME 错误。生产环境请让这些资源缺失时返回真实 `404`。