Skip to content

Commit 2320c76

Browse files
Evil0ctalEvil0ctal
committed
Add GitHub workflow files
1 parent e19f14c commit 2320c76

File tree

3 files changed

+437
-0
lines changed

3 files changed

+437
-0
lines changed

‎.github/DOCKER_DEPLOYMENT.md‎

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
# Docker Hub 自动部署配置指南
2+
3+
本文档说明如何配置 GitHub Actions 自动构建和发布 Docker 镜像到 Docker Hub。
4+
5+
## 📋 前置要求
6+
7+
1. **Docker Hub 账号**
8+
- 如果没有账号，请访问 https://hub.docker.com/ 注册
9+
- 记住你的用户名（例如：`evil0ctal`）
10+
11+
2. **Docker Hub Access Token**
12+
- 登录 Docker Hub
13+
- 进入 **Account Settings → Security → Access Tokens**
14+
- 点击 **New Access Token**
15+
- 名称：`GitHub Actions`
16+
- 权限：`Read, Write, Delete`
17+
- 复制生成的 Token（只显示一次，请妥善保存）
18+
19+
## 🔐 配置 GitHub Secrets
20+
21+
### 步骤 1: 进入仓库设置
22+
23+
1. 打开你的 GitHub 仓库
24+
2. 点击 **Settings** 标签
25+
3. 在左侧菜单选择 **Secrets and variables → Actions**
26+
27+
### 步骤 2: 添加 Secrets
28+
29+
点击 **New repository secret** 按钮，添加以下两个 Secret：
30+
31+
#### Secret 1: DOCKERHUB_USERNAME
32+
33+
- **Name**: `DOCKERHUB_USERNAME`
34+
- **Value**: 你的 Docker Hub 用户名（例如：`evil0ctal`）
35+
- 点击 **Add secret**
36+
37+
#### Secret 2: DOCKERHUB_TOKEN
38+
39+
- **Name**: `DOCKERHUB_TOKEN`
40+
- **Value**: 从 Docker Hub 复制的 Access Token
41+
- 点击 **Add secret**
42+
43+
### 验证配置
44+
45+
完成后，你应该看到两个 Secrets：
46+
```
47+
✅ DOCKERHUB_USERNAME
48+
✅ DOCKERHUB_TOKEN
49+
```
50+
51+
## 🚀 工作流说明
52+
53+
### 触发条件
54+
55+
工作流会在以下情况自动运行：
56+
57+
1. **推送到主分支** (`main`)
58+
```bash
59+
git push origin main
60+
```
61+
62+
2. **推送到开发分支** (`develop`)
63+
```bash
64+
git push origin develop
65+
```
66+
67+
3. **推送版本标签** (例如 `v2.0.0`)
68+
```bash
69+
git tag v2.0.0
70+
git push origin v2.0.0
71+
```
72+
73+
4. **修改 API 服务代码** (`api-service/**`)
74+
- 任何对 `api-service` 目录下文件的修改
75+
76+
5. **手动触发**
77+
- 在 GitHub Actions 页面点击 "Run workflow"
78+
79+
### 生成的镜像标签
80+
81+
根据不同的触发条件，会生成不同的标签：
82+
83+
| 触发条件 | 生成的标签 | 示例 |
84+
|---------|-----------|------|
85+
| 推送到 `main` | `latest` | `evil0ctal/wechat-decrypt-api:latest` |
86+
| 推送到 `main` | `main` | `evil0ctal/wechat-decrypt-api:main` |
87+
| 推送到 `develop` | `develop` | `evil0ctal/wechat-decrypt-api:develop` |
88+
| 版本标签 `v2.0.0` | `2.0.0`, `2.0`, `2`, `latest` | `evil0ctal/wechat-decrypt-api:2.0.0` |
89+
| 提交 SHA | `main-abc1234` | `evil0ctal/wechat-decrypt-api:main-abc1234` |
90+
91+
### 支持的平台
92+
93+
工作流会构建多平台镜像：
94+
- ✅ `linux/amd64` (x86_64 - Intel/AMD 处理器)
95+
- ✅ `linux/arm64` (ARM64 - Apple Silicon, Raspberry Pi 4+)
96+
97+
## 📦 使用发布的镜像
98+
99+
### 拉取最新版本
100+
101+
```bash
102+
docker pull evil0ctal/wechat-decrypt-api:latest
103+
```
104+
105+
### 拉取特定版本
106+
107+
```bash
108+
docker pull evil0ctal/wechat-decrypt-api:2.0.0
109+
```
110+
111+
### 使用发布的镜像运行服务
112+
113+
```bash
114+
# 直接运行
115+
docker run -d \
116+
--name wechat-decrypt-api \
117+
-p 3000:3000 \
118+
evil0ctal/wechat-decrypt-api:latest
119+
120+
# 或使用 docker-compose.yml
121+
```
122+
123+
更新 `api-service/docker-compose.yml`：
124+
125+
```yaml
126+
version: '3.8'
127+
128+
services:
129+
wechat-decrypt-api:
130+
image: evil0ctal/wechat-decrypt-api:latest # 使用 Docker Hub 镜像
131+
# image: wechat-decrypt-api:playwright # 注释掉本地构建
132+
# build:
133+
# context: .
134+
# dockerfile: Dockerfile
135+
container_name: wechat-decrypt-api
136+
ports:
137+
- "3000:3000"
138+
# ... 其他配置保持不变
139+
```
140+
141+
然后运行：
142+
143+
```bash
144+
docker-compose pull # 拉取最新镜像
145+
docker-compose up -d # 启动服务
146+
```
147+
148+
## 🔍 查看构建状态
149+
150+
### 方法 1: GitHub Actions 页面
151+
152+
1. 进入仓库的 **Actions** 标签
153+
2. 选择 **Build and Push Docker Image** 工作流
154+
3. 查看最近的运行记录
155+
156+
### 方法 2: README Badge
157+
158+
在 `README.md` 中添加状态徽章：
159+
160+
```markdown
161+
[![Docker Image CI](https://github.com/Evil0ctal/WeChat-Channels-Video-File-Decryption/actions/workflows/docker-image.yml/badge.svg)](https://github.com/Evil0ctal/WeChat-Channels-Video-File-Decryption/actions/workflows/docker-image.yml)
162+
```
163+
164+
### 方法 3: Docker Hub
165+
166+
访问 https://hub.docker.com/r/evil0ctal/wechat-decrypt-api 查看发布的镜像。
167+
168+
## 🐛 故障排除
169+
170+
### 问题 1: 认证失败
171+
172+
**错误信息**:
173+
```
174+
Error: failed to authorize: failed to fetch anonymous token
175+
```
176+
177+
**解决方案**:
178+
1. 检查 `DOCKERHUB_USERNAME` 是否正确
179+
2. 检查 `DOCKERHUB_TOKEN` 是否有效
180+
3. 确保 Token 权限包含 `Read, Write, Delete`
181+
4. 重新生成 Token 并更新 Secret
182+
183+
### 问题 2: 推送失败 (权限问题)
184+
185+
**错误信息**:
186+
```
187+
Error: denied: requested access to the resource is denied
188+
```
189+
190+
**解决方案**:
191+
1. 确保仓库名称正确（`<username>/wechat-decrypt-api`）
192+
2. 在 Docker Hub 创建仓库（如果不存在）
193+
3. 检查 Token 权限
194+
195+
### 问题 3: 构建超时
196+
197+
**解决方案**:
198+
- GitHub Actions 免费版有时间限制
199+
- 考虑优化 Dockerfile（使用缓存、多阶段构建）
200+
- 当前 Dockerfile 已优化，通常在 5-10 分钟内完成
201+
202+
### 问题 4: 多平台构建失败
203+
204+
**解决方案**:
205+
- 某些平台可能构建失败（如 arm64）
206+
- 可以临时移除有问题的平台：
207+
```yaml
208+
platforms: linux/amd64 # 只构建 amd64
209+
```
210+
211+
## 📝 工作流文件说明
212+
213+
工作流配置文件位于：`.github/workflows/docker-image.yml`
214+
215+
### 关键配置
216+
217+
1. **触发条件** (`on`)
218+
- 控制何时自动运行
219+
220+
2. **环境变量** (`env`)
221+
- `IMAGE_NAME`: Docker 镜像名称
222+
223+
3. **构建步骤** (`steps`)
224+
- Checkout 代码
225+
- 设置 QEMU（多平台支持）
226+
- 设置 Docker Buildx
227+
- 登录 Docker Hub
228+
- 提取元数据（标签）
229+
- 构建并推送镜像
230+
- 更新 Docker Hub 描述
231+
232+
4. **缓存** (`cache-from/cache-to`)
233+
- 使用 GitHub Actions 缓存加速构建
234+
235+
## 🎯 最佳实践
236+
237+
### 1. 版本标签
238+
239+
使用语义化版本标签：
240+
241+
```bash
242+
# 主版本更新
243+
git tag v3.0.0
244+
git push origin v3.0.0
245+
246+
# 次版本更新
247+
git tag v2.1.0
248+
git push origin v2.1.0
249+
250+
# 修订版更新
251+
git tag v2.0.1
252+
git push origin v2.0.1
253+
```
254+
255+
### 2. 开发流程
256+
257+
```bash
258+
# 开发阶段：推送到 develop 分支
259+
git checkout develop
260+
git add .
261+
git commit -m "feat: add new feature"
262+
git push origin develop
263+
# 生成镜像: wechat-decrypt-api:develop
264+
265+
# 准备发布：合并到 main 并打标签
266+
git checkout main
267+
git merge develop
268+
git tag v2.1.0
269+
git push origin main --tags
270+
# 生成镜像: wechat-decrypt-api:latest, wechat-decrypt-api:2.1.0
271+
```
272+
273+
### 3. 回滚到旧版本
274+
275+
```bash
276+
# 拉取特定版本
277+
docker pull evil0ctal/wechat-decrypt-api:2.0.0
278+
279+
# 更新 docker-compose.yml
280+
# image: evil0ctal/wechat-decrypt-api:2.0.0
281+
282+
docker-compose up -d
283+
```
284+
285+
## 🔒 安全建议
286+
287+
1. **永远不要** 在代码中硬编码 Token
288+
2. **定期轮换** Docker Hub Access Token
289+
3. **最小权限原则** - Token 只授予必要的权限
290+
4. **审计日志** - 定期检查 Docker Hub 的访问日志
291+
5. **私有镜像** - 如需私有，在 Docker Hub 设置仓库为 Private
292+
293+
## 📚 相关链接
294+
295+
- [GitHub Actions 文档](https://docs.github.com/en/actions)
296+
- [Docker Hub 文档](https://docs.docker.com/docker-hub/)
297+
- [Docker Build Push Action](https://github.com/docker/build-push-action)
298+
- [项目 README](../README.md)
299+
- [API 服务文档](../api-service/README.md)
300+
301+
## ✅ 检查清单
302+
303+
部署前确保：
304+
305+
- [ ] Docker Hub 账号已创建
306+
- [ ] Docker Hub Access Token 已生成
307+
- [ ] GitHub Secrets 已配置（`DOCKERHUB_USERNAME` 和 `DOCKERHUB_TOKEN`）
308+
- [ ] 工作流文件已提交到仓库
309+
- [ ] 已测试触发工作流（推送代码或手动运行）
310+
- [ ] 构建成功且镜像已发布到 Docker Hub
311+
- [ ] 可以从 Docker Hub 拉取并运行镜像
312+
313+
---
314+
315+
**作者**: Evil0ctal
316+
**更新时间**: 2025-10-17
317+
**版本**: 1.0

‎.github/workflows/docker-image.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Build and Push Docker Image
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- develop
8+
tags:
9+
- 'v*.*.*'
10+
paths:
11+
- 'api-service/**'
12+
- '.github/workflows/docker-image.yml'
13+
pull_request:
14+
branches:
15+
- main
16+
paths:
17+
- 'api-service/**'
18+
workflow_dispatch:
19+
20+
env:
21+
REGISTRY: docker.io
22+
IMAGE_NAME: ${{ secrets.DOCKERHUB_USERNAME }}/wechat-decrypt-api
23+
24+
jobs:
25+
build-and-push:
26+
runs-on: ubuntu-latest
27+
permissions:
28+
contents: read
29+
packages: write
30+
31+
steps:
32+
- name: Checkout repository
33+
uses: actions/checkout@v4
34+
35+
- name: Set up QEMU
36+
uses: docker/setup-qemu-action@v3
37+
38+
- name: Set up Docker Buildx
39+
uses: docker/setup-buildx-action@v3
40+
41+
- name: Log in to Docker Hub
42+
if: github.event_name != 'pull_request'
43+
uses: docker/login-action@v3
44+
with:
45+
username: ${{ secrets.DOCKERHUB_USERNAME }}
46+
password: ${{ secrets.DOCKERHUB_TOKEN }}
47+
48+
- name: Extract metadata (tags, labels)
49+
id: meta
50+
uses: docker/metadata-action@v5
51+
with:
52+
images: ${{ env.IMAGE_NAME }}
53+
tags: |
54+
type=ref,event=branch
55+
type=ref,event=pr
56+
type=semver,pattern={{version}}
57+
type=semver,pattern={{major}}.{{minor}}
58+
type=semver,pattern={{major}}
59+
type=raw,value=latest,enable={{is_default_branch}}
60+
type=sha,prefix={{branch}}-
61+
62+
- name: Build and push Docker image
63+
uses: docker/build-push-action@v5
64+
with:
65+
context: ./api-service
66+
file: ./api-service/Dockerfile
67+
platforms: linux/amd64,linux/arm64
68+
push: ${{ github.event_name != 'pull_request' }}
69+
tags: ${{ steps.meta.outputs.tags }}
70+
labels: ${{ steps.meta.outputs.labels }}
71+
cache-from: type=gha
72+
cache-to: type=gha,mode=max
73+
74+
- name: Docker Hub Description
75+
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
76+
uses: peter-evans/dockerhub-description@v4
77+
with:
78+
username: ${{ secrets.DOCKERHUB_USERNAME }}
79+
password: ${{ secrets.DOCKERHUB_TOKEN }}
80+
repository: ${{ env.IMAGE_NAME }}
81+
readme-filepath: ./api-service/README.md

0 commit comments

Comments
 (0)