### 项目说明

本项目用于构建通用的静态web服务docker模版，纯静态web服务可以使用本项目产出的docker镜像快速搭建稳定的线上服务。


### 原理说明

每次创建新 tag 时触发工作流，同时发布 tag名和latest两个镜像版本到gitea自动的docker管理平台。
使用Dockerfile构建基于nginx的镜像，具体使用中，可以宿主机 default.conf / nginx 工作目录到宿主机，宿主机只需要首次部署时构建 docker-compose，后续部署只需替换nginx目录即可。


### 用法说明

#### 设计约束

- 基础镜像：nginx:alpine（体积小）
- 不考虑 TLS（HTTPS 请由外部反向代理/网关处理）
- 站点内容不随镜像打包，运行时挂载 `./site` 到容器 `/usr/share/nginx/html`

#### 目录结构

```
.
├─ Dockerfile
├─ nginx/
│  └─ default.conf         # Nginx 静态站点配置（可按项目调整）
├─ example/
│  ├─ docker-compose.yml   # 本地/线上均可复用的示例
│  └─ site/                # 示例静态资源（仅本地验证用）
└─ .gitea/workflows/
	 └─ build.yml            # 基于 tag 的构建与推送
```

#### 本地构建镜像

```bash
docker build -t static-web:latest .
```

#### 使用 docker 命令启动服务

```bash
# 在仓库根目录下准备你的站点目录
mkdir -p site && echo '<h1>Hello</h1>' > site/index.html

docker run -d \
	--name static-web \
	-p 8080:80 \
	-v "$(pwd)/nginx":/etc/nginx/conf.d:ro \
	-v "$(pwd)/site":/usr/share/nginx/html:ro \
	static-web:latest

# 访问： http://localhost:8080
```


#### 使用 docker-compose.yml 命令启动服务

```bash
cd example
# 可直接使用示例站点：example/site/index.html
docker compose up -d

# 访问： http://localhost:8080
```

### 版本与发布

- 推荐使用语义化标签发布：例如 `v1.0.0`、`v1.0.1`。
- 推送 tag 后，CI 会构建并推送两个镜像标签：`<tag>` 与 `latest`。

### CI/CD（Gitea Actions）

工作流文件：`.gitea/workflows/build.yml`

- 触发条件：push tag（匹配 `v*`）。
- 必需 secrets（在仓库设置中配置）：
	- `REGISTRY_HOST`：Docker Registry 主机（例如 `registry.example.com`）。
	- `REGISTRY_USERNAME` / `REGISTRY_PASSWORD`：用于登录 Registry 的凭据。
	- `REGISTRY_IMAGE`：完整镜像名（例如 `registry.example.com/org/static-web`）。
- Runner 需具备 Docker 执行环境；`runs-on` 使用的标签可按你的 Runner 调整。

本地验证镜像成功推送后，线上 `docker-compose.yml` 可使用远程镜像：

```yaml
services:
	web:
		image: registry.example.com/org/static-web:latest
		ports:
			- "8080:80"
		volumes:
			- ./nginx:/etc/nginx/conf.d:ro
			- ./site:/usr/share/nginx/html:ro
```

### Nginx 配置要点

- 根目录：`/usr/share/nginx/html`（通过卷挂载提供内容）。
- Gzip：对 CSS/JS/JSON/SVG 等启用压缩。
- 缓存：对静态资源（js/css/img/fonts）设置长缓存；HTML 禁止缓存。
- 安全：默认开启 `X-Content-Type-Options`、`X-Frame-Options`、`Referrer-Policy`。`CSP` 默认注释，如需请按项目定制。
- SPA 场景：若需前端路由降级到 `index.html`，可将 `location /` 中的 `try_files` 调整为 `try_files $uri /index.html;`。

### 常见问题

- 端口冲突：修改 `-p 8080:80` 映射或释放宿主机端口。
- 权限问题：确保宿主机 `./nginx` 与 `./site` 对 Runner/部署主机可读；挂载只读可避免误改。
- 缓存过期：生产环境建议为静态资源加内容哈希；或调整 `Cache-Control` 策略。
- CI 无法登录 Registry：核对 `REGISTRY_HOST`、用户名/密码与网络可达性，Runner 需具备 `docker login` 能力。