lunar-mini/.gitea/docs/AUTO_DEPLOY_1PANEL.md

1Panel 自动部署配置指南

本文档说明如何配置 1Panel 实现后端服务的全自动部署。

架构说明

代码 Push → Gitea Actions 构建 → 保存部署包 → 自动部署到 1Panel 容器 → 重启服务 → 发送通知

前提条件

1. ✅ 1Panel 已安装在 doc79 服务器
2. ✅ Gitea Actions runner 已配置（lunar-ci）
3. ✅ Docker 已安装并可被 runner 访问

配置步骤

1. 在 1Panel 中创建容器

方法 1：通过 1Panel 网页界面

1. 登录 1Panel 管理界面

2. 进入 容器 → 创建容器

3. 配置如下：

   • 名称: lunar-server
   • 镜像: golang:1.22-bookworm
   • 端口映射: 8080:8080（根据你的应用端口调整）
   • 挂载卷:
     • 主机路径: /opt/lunar/production/current
     • 容器路径: /app
   • 重启策略: unless-stopped
   • 启动命令: /app/bin/server
   • 环境变量: 根据需要添加（如数据库连接等）

4. 点击 创建 启动容器

方法 2：通过命令行

SSH 到 doc79 服务器，执行：

# 创建部署目录
sudo mkdir -p /opt/lunar/production/current
sudo mkdir -p /opt/lunar/backups

# 创建容器
docker run -d \
  --name lunar-server \
  -v /opt/lunar/production/current:/app \
  -p 8080:8080 \
  --restart unless-stopped \
  golang:1.22-bookworm \
  /app/bin/server

2. 配置 Gitea Actions Variables

由于 Gitea Actions API 不可用，需要直接写入 MySQL 数据库。

# SSH 到 Gitea 服务器
ssh doc79

# 连接 MySQL
mysql -u gitea -p gitea

执行以下 SQL：

-- 容器名称（可选，默认为 lunar-server）
INSERT INTO action_variable (owner_id, repo_id, name, data, created_unix, updated_unix)
VALUES (0, 0, 'CONTAINER_NAME', 'lunar-server', UNIX_TIMESTAMP(), UNIX_TIMESTAMP())
ON DUPLICATE KEY UPDATE data = 'lunar-server', updated_unix = UNIX_TIMESTAMP();

-- 部署目录（可选，默认为 /opt/lunar/production）
INSERT INTO action_variable (owner_id, repo_id, name, data, created_unix, updated_unix)
VALUES (0, 0, 'DEPLOY_DIR', '/opt/lunar/production', UNIX_TIMESTAMP(), UNIX_TIMESTAMP())
ON DUPLICATE KEY UPDATE data = '/opt/lunar/production', updated_unix = UNIX_TIMESTAMP();

-- 备份目录（可选，默认为 /opt/lunar/backups）
INSERT INTO action_variable (owner_id, repo_id, name, data, created_unix, updated_unix)
VALUES (0, 0, 'BACKUP_DIR', '/opt/lunar/backups', UNIX_TIMESTAMP(), UNIX_TIMESTAMP())
ON DUPLICATE KEY UPDATE data = '/opt/lunar/backups', updated_unix = UNIX_TIMESTAMP();

3. 配置 Runner 权限

确保 Gitea Actions runner 有权限执行 Docker 命令。

检查 runner 配置

# SSH 到 doc79
ssh doc79

# 查看 runner 配置
sudo cat /etc/act_runner-lunar/config.yaml

确保配置中包含 Docker socket 挂载：

container:
  options: -v /var/run/docker.sock:/var/run/docker.sock

如果没有，需要修改配置并重启 runner：

# 编辑配置
sudo nano /etc/act_runner-lunar/config.yaml

# 添加或修改 container 部分
container:
  options: -v /var/run/docker.sock:/var/run/docker.sock -v /opt/lunar:/opt/lunar

# 重启 runner
sudo systemctl restart act_runner-lunar.service

4. 测试自动部署

配置完成后，推送代码到 main 分支触发自动部署：

# 修改后端代码
cd /Users/gouki/server/wwwroot/own/lunar
echo "// test auto deploy" >> server/cmd/main.go

# 提交并推送
git add server/
git commit -m "test: 测试自动部署"
git push origin main

5. 验证部署

查看 Actions 日志

1. 访问 Gitea 网页界面
2. 进入仓库 → Actions
3. 查看最新的工作流运行日志
4. 确认 "Deploy to production" 步骤成功

查看容器状态

# SSH 到 doc79
ssh doc79

# 查看容器状态
docker ps | grep lunar-server

# 查看容器日志
docker logs -f lunar-server

# 查看部署文件
ls -la /opt/lunar/production/current/

查看通知

检查 Telegram 和 Discord 是否收到部署成功通知。

部署流程详解

1. 构建阶段（在 runner 容器中）

• 拉取代码
• 安装依赖
• 运行测试
• 构建二进制文件
• 构建前端（如果存在）
• 创建部署包 deploy.tar.gz

2. 保存阶段（在 runner 主机上）

• 将部署包保存到 /opt/lunar/ci-artifacts/
• 保留历史版本和 latest 版本

3. 部署阶段（在 runner 主机上）

执行 deploy.sh 脚本：

1. 备份当前版本

   • 将 /opt/lunar/production/current 打包到 /opt/lunar/backups/backup_TIMESTAMP.tar.gz

2. 解压新版本

   • 解压 deploy.tar.gz 到临时目录
   • 移动到 /opt/lunar/production/current

3. 设置权限

   • 确保 bin/server 可执行

4. 重启容器

   • 执行 docker restart lunar-server
   • 等待 3 秒
   • 检查容器状态

5. 清理旧备份

   • 保留最近 5 个备份
   • 删除更早的备份

4. 通知阶段

• 部署成功：发送 ✅ 通知到 Telegram 和 Discord
• 部署失败：发送 ❌ 通知到 Telegram 和 Discord

故障排查

部署失败：容器不存在

错误信息: Docker 容器不存在: lunar-server

解决方法:

1. 检查容器是否已创建：docker ps -a | grep lunar-server
2. 如果没有，按照上述步骤创建容器
3. 如果容器名不同，修改 Gitea Actions Variable CONTAINER_NAME

部署失败：权限不足

错误信息: permission denied while trying to connect to the Docker daemon socket

解决方法:

1. 检查 runner 配置是否挂载了 Docker socket
2. 重启 runner 服务：sudo systemctl restart act_runner-lunar.service

容器重启后立即退出

可能原因:

1. 二进制文件损坏或不完整
2. 端口被占用
3. 环境变量缺失
4. 数据库连接失败

排查步骤:

# 查看容器日志
docker logs lunar-server

# 检查二进制文件
ls -lh /opt/lunar/production/current/bin/server
file /opt/lunar/production/current/bin/server

# 手动运行测试
docker run --rm -it \
  -v /opt/lunar/production/current:/app \
  golang:1.22-bookworm \
  /app/bin/server

备份占用空间过大

解决方法:

# 手动清理旧备份
ls -lh /opt/lunar/backups/
rm /opt/lunar/backups/backup_20240101_*.tar.gz

# 或修改 deploy.sh 中的保留数量
# 将 "tail -n +6" 改为 "tail -n +3" 只保留 2 个备份

回滚操作

如果部署后发现问题，可以快速回滚到之前的版本：

# SSH 到 doc79
ssh doc79

# 查看备份列表
ls -lh /opt/lunar/backups/

# 选择要恢复的备份（例如 backup_20260807_120000.tar.gz）
BACKUP_FILE="/opt/lunar/backups/backup_20260807_120000.tar.gz"

# 停止容器
docker stop lunar-server

# 恢复备份
rm -rf /opt/lunar/production/current
tar -xzf "$BACKUP_FILE" -C /opt/lunar/production/

# 重启容器
docker start lunar-server

# 查看日志
docker logs -f lunar-server

高级配置

自定义容器环境变量

如果你的应用需要环境变量（如数据库连接），可以在 1Panel 中配置：

1. 编辑容器
2. 添加环境变量：
   • DB_HOST=localhost
   • DB_PORT=3306
   • DB_USER=lunar
   • DB_PASS=your_password
   • DB_NAME=lunar

或者在 docker run 命令中添加：

docker run -d \
  --name lunar-server \
  -v /opt/lunar/production/current:/app \
  -p 8080:8080 \
  -e DB_HOST=localhost \
  -e DB_PORT=3306 \
  -e DB_USER=lunar \
  -e DB_PASS=your_password \
  -e DB_NAME=lunar \
  --restart unless-stopped \
  golang:1.22-bookworm \
  /app/bin/server

使用 Docker Compose

如果你更喜欢使用 Docker Compose，可以创建 /opt/lunar/docker-compose.yml：

version: '3.8'

services:
  lunar-server:
    image: golang:1.22-bookworm
    container_name: lunar-server
    volumes:
      - /opt/lunar/production/current:/app
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=localhost
      - DB_PORT=3306
      - DB_USER=lunar
      - DB_PASS=your_password
      - DB_NAME=lunar
    restart: unless-stopped
    command: /app/bin/server

然后修改 deploy.sh 中的重启命令：

# 将
docker restart "$CONTAINER_NAME"

# 改为
cd /opt/lunar && docker-compose restart

健康检查

可以在 deploy.sh 中添加健康检查：

# 在 "等待容器启动" 后添加
log_info "执行健康检查..."
for i in {1..10}; do
  if curl -f http://localhost:8080/health; then
    log_info "✅ 健康检查通过"
    break
  fi
  if [ $i -eq 10 ]; then
    log_error "❌ 健康检查失败"
    exit 1
  fi
  sleep 2
done

安全建议

1. 限制 Docker socket 访问：只在必要的 runner 上挂载 Docker socket
2. 使用非 root 用户：在容器中使用非 root 用户运行应用
3. 定期清理备份：避免备份文件占用过多磁盘空间
4. 监控部署日志：定期检查 Actions 日志和容器日志
5. 备份数据库：部署前自动备份数据库（可选）

相关文件

• 部署脚本：.gitea/scripts/deploy.sh
• 通知脚本：.gitea/scripts/notify.sh
• 工作流配置：.gitea/workflows/server-deploy.yml
• Runner 配置：/etc/act_runner-lunar/config.yaml（在 doc79 上）

更新日志

• 2026-08-07: 初始版本，支持 1Panel Docker 容器自动部署