Add Docker Compose deployment setup

docs/docker-deploy.md

@@ -0,0 +1,195 @@
+# Docker / Compose 部署说明
+
+当前提供的是最小可用静态部署方案：
+
+- 构建阶段：在 Docker build 中执行 `npm run rebuild`
+- 运行阶段：使用 Nginx 提供 `dist/` 静态文件
+
+## 文件
+
+- `Dockerfile`
+- `docker-compose.yml`
+- `docker/nginx/default.conf`
+
+## 使用方式
+
+### 1. 准备环境变量
+
+确保仓库根目录有可用的 `.env`，或在执行 `docker compose` 前导出这些变量：
+
+- `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、域名配置
+- 还没有单独拆“构建容器”和“运行容器”的外部流水线
+- 还没有持久化部署产物或零停机切换策略