# Docker / Compose 部署说明

当前提供的是最小可用静态部署方案：

- 构建阶段：在 Docker build 中执行 `npm run rebuild`
- 运行阶段：使用 Nginx 提供 `dist/` 静态文件

## 文件

- `Dockerfile`
- `docker-compose.yml`
- `docker/nginx/default.conf`

## 使用方式

### 1. 准备环境变量

确保仓库根目录有可用的 `.env`，或在执行 `docker compose` 前导出这些变量：

- `PUBLIC_SITE_URL`
- `PUBLIC_GITEA_URL`
- `PUBLIC_GITHUB_URL`
- `PUBLIC_BLOG_URL`
- `PUBLIC_GITEA_USERNAME`
- `GITEA_BASE_URL`
- `GITEA_TOKEN`
- `GITEA_USERNAME`
- `SEAFILE_BASE_URL`
- `SEAFILE_TOKEN`

可选：

- `STRICT_SYNC`
- `HOMEPAGE_PORT`
- 其余同步调优参数

`docker-compose.yml` 会把这些值作为 **build args** 传给 Dockerfile，用于构建时同步和静态生成。

### 环境变量是怎么注入的

当前链路是：

```text
宿主机环境变量 / 项目根目录 .env
  -> docker compose 读取变量
  -> docker-compose.yml 的 build.args
  -> Dockerfile 的 ARG
  -> Dockerfile 的 ENV
  -> npm run rebuild
```

也就是说，`docker-compose.yml` 自己并不保存真实值，它只是引用变量，例如：

```yaml
args:
  GITEA_BASE_URL: ${GITEA_BASE_URL:-}
```

含义是：

- 如果宿主机环境或 `.env` 里有 `GITEA_BASE_URL`，就把它传进去
- 如果没有，就用空字符串

然后 `Dockerfile` 再接住：

```dockerfile
ARG GITEA_BASE_URL=""
ENV GITEA_BASE_URL="${GITEA_BASE_URL}"
```

这样 `npm run rebuild` 在镜像构建阶段就能读取到这些变量。

### `.env` 和 compose 的关系

当前项目里，同一个 `.env` 同时服务两条路径：

1. **本地直接执行**

```bash
npm run rebuild
```

Node 通过：

```bash
--env-file-if-exists=.env
```

读取 `.env`

2. **Docker Compose 构建**

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

Compose 会自动读取项目根目录 `.env`，并将变量传给 `build.args`

所以可以把 `.env` 理解成：

- 本地脚本运行配置
- Docker 构建时同步配置

共用的一份构建环境变量文件。

### 为什么用 build args 而不是运行时环境变量

因为这个项目的 Gitea / Seafile token 只在**构建阶段**需要：

- 构建时同步远端数据
- 构建时生成静态页面

最终运行时容器只是 Nginx 提供 `dist/`，不再访问 Gitea / Seafile，也不需要 token。

### 修改环境变量后要怎么生效

因为变量是注入到 **构建阶段** 的，所以修改 `.env` 后需要重新 build：

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

如果只执行：

```bash
docker compose restart
```

不会重新同步，也不会重新生成静态产物。

### 2. 构建并启动

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

默认会把站点暴露到：

```text
http://localhost:8080
```

如需修改端口：

```bash
HOMEPAGE_PORT=80 docker compose up -d --build
```

### 3. 查看日志

```bash
docker compose logs -f homepage
```

### 4. 停止

```bash
docker compose down
```

## 部署方式说明

当前 compose 方案是：

1. 构建镜像时执行 `npm run rebuild`
2. 生成 `dist/`
3. 将 `dist/` 拷贝进 Nginx 容器
4. 运行时只提供静态文件服务

这意味着：

- 运行中的容器不需要 Gitea / Seafile token
- token 只在镜像构建阶段使用
- 每次内容更新后，需要重新 build 镜像

## 与 AstrBot 的配合方式

如果后续由 AstrBot 触发重建，推荐：

1. AstrBot 在服务器上拉最新代码
2. AstrBot 执行 `docker compose up -d --build`
3. AstrBot 根据命令结果发送成功 / 失败通知

如果你想让 AstrBot 先单独判断同步 / 构建错误码，再决定是否部署，也可以先执行：

```bash
npm run rebuild
```

通过后再执行：

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

## 当前限制

- compose 里还没有反向代理、HTTPS、域名配置
- 还没有单独拆“构建容器”和“运行容器”的外部流水线
- 还没有持久化部署产物或零停机切换策略