238 lines
4.8 KiB
Markdown
238 lines
4.8 KiB
Markdown
# Gitea Actions 部署配置指南
|
||
|
||
## 前置要求
|
||
|
||
### 1. 确保 Gitea Actions 已启用
|
||
|
||
在 Gitea 管理员设置中：
|
||
- 进入 **Site Administration** → **Actions**
|
||
- 确保 **Actions** 功能已启用
|
||
- 检查 `app.ini` 配置：
|
||
|
||
```ini
|
||
[actions]
|
||
ENABLED = true
|
||
```
|
||
|
||
### 2. 安装并运行 Act Runner
|
||
|
||
Act Runner 是 Gitea Actions 的执行器，需要在服务器上运行。
|
||
|
||
#### 下载 Act Runner
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
cd /tmp
|
||
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.6/act_runner-linux-amd64
|
||
chmod +x act_runner-linux-amd64
|
||
sudo mv act_runner-linux-amd64 /usr/local/bin/act_runner
|
||
```
|
||
|
||
#### 注册 Runner
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
act_runner register \
|
||
--instance <your-gitea-url> \
|
||
--token <runner-token> \
|
||
--name my-runner \
|
||
--labels ubuntu-latest:docker://node:20-bullseye
|
||
```
|
||
|
||
**获取 Runner Token**：
|
||
1. 进入 Gitea：**Site Administration** → **Actions** → **Runners**
|
||
2. 点击 **New Runner**
|
||
3. 复制显示的 Token
|
||
|
||
#### 运行 Runner
|
||
|
||
```bash
|
||
# 作为服务运行（推荐）
|
||
sudo tee /etc/systemd/system/gitea-act-runner.service > /dev/null <<EOF
|
||
[Unit]
|
||
Description=Gitea Act Runner
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=root
|
||
WorkingDirectory=/opt/cloud-mcp
|
||
ExecStart=/usr/local/bin/act_runner daemon
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
EOF
|
||
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable gitea-act-runner
|
||
sudo systemctl start gitea-act-runner
|
||
sudo systemctl status gitea-act-runner
|
||
```
|
||
|
||
或者直接运行：
|
||
|
||
```bash
|
||
act_runner daemon
|
||
```
|
||
|
||
### 3. 配置 GitHub Secrets（在 Gitea 中）
|
||
|
||
在 Gitea 仓库中设置 Secrets：
|
||
|
||
1. 进入仓库：**Settings** → **Secrets** → **Actions**
|
||
2. 添加以下 Secrets：
|
||
|
||
```
|
||
SERVER_HOST=你的服务器IP或域名
|
||
SERVER_USERNAME=部署用户名（如 root 或 deployer）
|
||
SERVER_SSH_KEY=你的SSH私钥（完整内容，包括 -----BEGIN 和 -----END）
|
||
```
|
||
|
||
**生成 SSH 密钥对**（如果还没有）：
|
||
|
||
```bash
|
||
# 在本地或服务器上
|
||
ssh-keygen -t ed25519 -C "gitea-actions-deploy" -f ~/.ssh/gitea_deploy
|
||
|
||
# 将公钥添加到服务器的 authorized_keys
|
||
ssh-copy-id -i ~/.ssh/gitea_deploy.pub user@your-server
|
||
|
||
# 复制私钥内容作为 SERVER_SSH_KEY secret
|
||
cat ~/.ssh/gitea_deploy
|
||
```
|
||
|
||
### 4. 更新部署脚本路径
|
||
|
||
编辑 `.gitea/workflows/deploy.yml` 或 `deploy-simple.yml`，更新项目路径：
|
||
|
||
```yaml
|
||
cd /opt/cloud-mcp # 改为你的实际项目路径
|
||
```
|
||
|
||
## 工作流文件说明
|
||
|
||
项目包含两个工作流文件：
|
||
|
||
### deploy.yml
|
||
- 使用 SSH 密钥文件方式
|
||
- 包含清理步骤
|
||
|
||
### deploy-simple.yml（推荐）
|
||
- 使用环境变量方式
|
||
- 更详细的日志输出
|
||
- 更好的错误处理
|
||
|
||
## 测试部署
|
||
|
||
### 1. 手动触发
|
||
|
||
在 Gitea 仓库中：
|
||
- 进入 **Actions** 标签页
|
||
- 选择 **Deploy to Server** 工作流
|
||
- 点击 **Run workflow**
|
||
|
||
### 2. 推送代码触发
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "Test deployment"
|
||
git push origin main
|
||
```
|
||
|
||
### 3. 查看日志
|
||
|
||
在 Gitea 仓库的 **Actions** 页面查看工作流执行日志。
|
||
|
||
## 故障排查
|
||
|
||
### 工作流一直显示"等待中"
|
||
|
||
1. **检查 Runner 是否运行**：
|
||
```bash
|
||
sudo systemctl status gitea-act-runner
|
||
# 或
|
||
ps aux | grep act_runner
|
||
```
|
||
|
||
2. **检查 Runner 标签匹配**：
|
||
- 工作流中 `runs-on: ubuntu-latest`
|
||
- Runner 注册时需要包含 `ubuntu-latest` 标签
|
||
|
||
3. **查看 Runner 日志**：
|
||
```bash
|
||
sudo journalctl -u gitea-act-runner -f
|
||
```
|
||
|
||
### SSH 连接失败
|
||
|
||
1. **测试 SSH 连接**：
|
||
```bash
|
||
ssh -i ~/.ssh/deploy_key user@server
|
||
```
|
||
|
||
2. **检查 SSH 密钥格式**：
|
||
- 确保私钥包含完整的 `-----BEGIN` 和 `-----END` 行
|
||
- 确保没有多余的空格或换行
|
||
|
||
3. **检查服务器防火墙**：
|
||
```bash
|
||
# 确保 SSH 端口开放
|
||
sudo ufw allow 22
|
||
```
|
||
|
||
### 部署脚本执行失败
|
||
|
||
1. **检查脚本权限**：
|
||
```bash
|
||
chmod +x /opt/cloud-mcp/deploy-gitea.sh
|
||
```
|
||
|
||
2. **检查项目路径**：
|
||
- 确保工作流中的路径与实际路径一致
|
||
|
||
3. **查看服务器日志**：
|
||
```bash
|
||
tail -f /opt/cloud-mcp/deploy.log
|
||
```
|
||
|
||
## 安全建议
|
||
|
||
1. **使用专用部署用户**：
|
||
```bash
|
||
sudo adduser deployer
|
||
sudo usermod -aG docker deployer
|
||
```
|
||
|
||
2. **限制 SSH 密钥权限**：
|
||
- 使用 `command=` 限制 SSH 密钥只能执行特定命令
|
||
- 在 `~/.ssh/authorized_keys` 中：
|
||
```
|
||
command="/opt/cloud-mcp/deploy-gitea.sh" ssh-ed25519 AAAAC3...
|
||
```
|
||
|
||
3. **使用 SSH 密钥而非密码**：
|
||
- 禁用密码登录
|
||
- 只使用密钥认证
|
||
|
||
4. **定期轮换密钥**：
|
||
- 定期更新 SSH 密钥
|
||
- 更新 Gitea Secrets
|
||
|
||
## 验证部署
|
||
|
||
部署成功后，检查：
|
||
|
||
```bash
|
||
# 在服务器上
|
||
docker ps | grep cloud-mcp
|
||
docker logs cloud-mcp
|
||
```
|
||
|
||
## 下一步
|
||
|
||
- 配置自动部署触发条件
|
||
- 添加部署通知（邮件、Slack 等）
|
||
- 设置部署回滚机制
|
||
|