# 2.7 Docker 快速体验

:::tip 概述
`deploy/docker-compose.yaml` 编排了应用、Nginx、MySQL、Redis 四个容器，一键拉起完整运行环境。适合快速体验与作为生产部署的参照。
:::

## 编排拓扑

```text
浏览器
  │
  ├─ :8000 ──→ admin-server（应用，多阶段构建的精简镜像）
  │                │
  │                ├─ mysql:8.0（127.0.0.1:3306 仅回环绑定）
  │                └─ redis:7（127.0.0.1:6379 仅回环绑定）
  │
  └─ :8081 ──→ nginx（只读挂载 upload 目录，直供上传文件，
                    temp 目录封禁）
```

## 启动步骤

```bash
# 1. 准备环境变量（与 .env.example 同款友好名）
cp .env.example .env
# 按需修改数据库/Redis 密码、JWT 密钥、文件域名

# 2. 在项目根构建并启动（根 .env 须经 --env-file 显式传入）
docker compose --env-file .env -f deploy/docker-compose.yaml up -d --build

# 3. 数据库无需手工初始化：MySQL 数据卷为空时
#    自动导入 document/mysql 定稿脚本（仅首次执行一次）
```

## 环境变量映射

compose 不透传 `.env` 原名，而是把友好名映射为 `APP_` 规范键：

```yaml
environment:
  APP_DATABASE_DEFAULT_HOST: ${MYSQL_HOST}
  APP_REDIS_DEFAULT_ADDRESS: ${REDIS_ADDR}
  APP_JWT_SECRET: ${JWT_SECRET}
  APP_FILE_UPLOADDIR: /data/upload
  APP_FILE_DOMAINURL: ${FILE_DOMAIN_URL}
```

## 卷与持久化

| 卷/挂载 | 挂载点 | 说明 |
|---|---|---|
| mysql_data | MySQL 数据目录 | 数据库持久化 |
| redis_data | Redis 数据目录 | 缓存持久化 |
| ../upload（bind） | 应用 /data/upload（rw）+ nginx（ro） | 上传文件，nginx 直供；宿主目录已有文件直接可见 |

## 镜像要点

`deploy/Dockerfile` 为多阶段构建：

- 编译阶段：`golang:1.27-alpine`，`CGO_ENABLED=0` + 去符号表压缩体积
- 运行阶段：`alpine:3.22` + 时区与证书，非 root 运行，仅带二进制、config、resource、templates；内置健康检查（/api/health）

## 验证

```bash
docker compose --env-file .env -f deploy/docker-compose.yaml ps   # 四容器 healthy
curl http://127.0.0.1:8000/api/health                             # 应用就绪
```

生产环境的完整部署清单（含 Nginx 站点配置、安全加固）见 [第 11 章 运维部署](/zh/deploy/checklist.html)。

## 下一步

→ [2.8 常见问题 FAQ](/zh/quickstart/faq.html)