Merge pull request #14 from oldjs/go-callback

Go callback

Author: shuguangnet

.github/workflows/go-test.yml

@@ -0,0 +1,131 @@
+name: Go Callback Handler Test
+
+on:
+  push:
+    branches: [main, go-callback]
+  pull_request:
+    branches: [main, go-callback]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Cache Go modules and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+
+      - name: Install dependencies
+        run: go mod download
+
+      - name: Build application
+        run: go build -v -o ./myapp ./go/callback/main.go
+
+      - name: Create test files
+        run: |
+          echo "port=8080" > backup.conf
+          echo "callback_secret=my-test-secret" >> backup.conf
+          echo "scriptpath=./docker-backup.sh" >> backup.conf
+
+      - name: Run integration test
+        run: |
+          # Start a test container for backup
+          echo "Starting a test Docker container..."
+          docker run -d --name test-container nginx:alpine
+          echo "Test container started."
+
+          # Start the callback handler application in the background
+          nohup ./myapp > app.log 2>&1 &
+
+          # Health check - wait for the server to be ready (max 30 seconds)
+          for i in {1..30}; do
+              if curl -s http://localhost:8080 >/dev/null; then
+                  echo "Server is ready"
+                  break
+              fi
+              echo "Waiting for server to be ready..."
+              sleep 1
+          done
+
+          # Prepare and send a simulated external callback (POST request)
+          # Include the test container name in the args
+          SIGNATURE=$(echo -n '{"args":["test-container"]}' | openssl dgst -sha256 -hmac "my-test-secret" | sed 's/^.* //')
+          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST http://localhost:8080/backup \
+              -H "Content-Type: application/json" \
+              -H "X-Signature: sha256=$SIGNATURE" \
+              -d '{"args":["test-container"]}')
+
+          # Extract response body and status code
+          RESPONSE_BODY=$(echo "$RESPONSE" | head -n -1)
+          STATUS_CODE=$(echo "$RESPONSE" | tail -n 1)
+
+          # Verify response
+          if [ "$STATUS_CODE" != "200" ]; then
+              echo "Test failed: Expected status code 200, got $STATUS_CODE"
+              echo "Response: $RESPONSE_BODY"
+              # Output app logs for debugging
+              echo "=== App logs ==="
+              cat app.log
+              echo "=== End of app logs ==="
+              # Output Docker logs for the test container
+              echo "=== Test container logs ==="
+              docker logs test-container || true
+              echo "=== End of test container logs ==="
+              exit 1
+          fi
+
+          if [[ "$RESPONSE_BODY" != *"Backup initiated successfully"* ]]; then
+              echo "Test failed: Expected response body to contain 'Backup initiated successfully'"
+              echo "Response: $RESPONSE_BODY"
+              # Output app logs for debugging
+              echo "=== App logs ==="
+              cat app.log
+              echo "=== End of app logs ==="
+              # Output Docker logs for the test container
+              echo "=== Test container logs ==="
+              docker logs test-container || true
+              echo "=== End of test container logs ==="
+              exit 1
+          fi
+
+          echo "Callback handler test passed"
+
+          # Cleanup
+          killall myapp || true
+          docker rm -f test-container || true
+
+      - name: Output application logs
+        if: always()
+        run: cat app.log
+
+      - name: List backup artifacts (if any)
+        if: always()
+        run: |
+          echo "=== Listing Docker backup artifacts ==="
+          # List directories that match the backup pattern created by docker-backup.sh
+          echo "Backup directories:"
+          ls -la /tmp/docker-backups/ 2>/dev/null || echo "No backup directory found at /tmp/docker-backups/"
+
+          # If backup directories exist, show their contents
+          if [[ -d "/tmp/docker-backups" ]]; then
+            for backup_dir in /tmp/docker-backups/*/; do
+              if [[ -d "$backup_dir" ]]; then
+                echo "Contents of $backup_dir:"
+                ls -la "$backup_dir"
+                echo "---"
+              fi
+            done
+          fi
+          echo "=== End of Docker backup artifact listing ==="

backup.conf

@@ -214,4 +214,10 @@ RUN_BACKUP_VERIFICATION=true
 # - CONTAINER_EXCLUDE_MOUNTS=true/false
 # - CONTAINER_PAUSE_DURING_BACKUP=true/false
 # - CONTAINER_PRE_BACKUP_SCRIPT="/path/to/script.sh"
-# - CONTAINER_POST_BACKUP_SCRIPT="/path/to/script.sh" 
+# - CONTAINER_POST_BACKUP_SCRIPT="/path/to/script.sh" 
+# ============================================================================
+# 回调配置
+# ============================================================================
+
+# 回调密钥（用于验证回调请求的安全性）
+callback_secret="a_very_secure_random_string_12345!@#$%^&*()"

go.mod

@@ -0,0 +1,3 @@
+module dcoker_backup_script
+
+go 1.24.4

go/callback/README.md

@@ -0,0 +1,110 @@
+# 安全回调服务器
+
+## 功能简介
+
+此工具提供了一个带签名验证的安全回调接口，用于触发 Docker 容器和卷的备份操作。
+
+## 完整使用指南
+
+有关如何安装、配置和使用此回调服务器的完整指南，请参阅 [USAGE.md](USAGE.md) 文件。
+
+## 配置
+
+在使用此回调服务器之前，您需要在项目根目录下的 `backup.conf` 文件中配置 `callback_secret`。
+
+```bash
+# backup.conf
+callback_secret=your_secret_key_here
+```
+
+## 编译服务器
+
+在 `go/callback/` 目录中运行以下命令来编译服务器：
+
+```bash
+go build -o callback_server.exe .
+```
+
+这将生成一个名为 `callback_server.exe` 的可执行文件（在 Windows 上）。
+
+## 运行服务器
+
+在 `go/callback/` 目录中运行生成的可执行文件：
+
+```bash
+./callback_server.exe
+```
+
+服务器将在 `localhost:47731` 启动。
+
+## API 端点
+
+### `POST /backup`
+
+此端点用于触发备份操作。
+
+**Headers:**
+
+- `X-Signature`: 请求签名，用于验证请求来源。签名是使用配置的 `callback_secret` 对请求体进行 HMAC-SHA256 计算得出的。
+
+**Request Body:**
+
+```json
+{
+  "args": ["arg1", "arg2"]
+}
+```
+
+- `args`: 传递给备份脚本的参数数组。
+
+## 编译并使用客户端示例
+
+在 `go/callback/` 目录中运行以下命令来编译客户端示例：
+
+```bash
+go build -o client_example.exe client_example.go
+```
+
+由于 `client_example.go` 文件被构建标签 `//go:build ignore` 标记，所以编译时必须显式指定文件名。
+
+然后可以使用以下命令来调用回调接口：
+
+```bash
+./client_example.exe -a --volumes
+```
+
+## Client Examples
+
+### Python 示例
+
+依赖安装: `pip install requests`，运行命令: `python client_example.py [args...]`
+
+### JavaScript (Node.js) 示例
+
+依赖安装: 无需额外依赖，运行命令: `node client_example.js [args...]`
+
+### TypeScript 示例
+
+依赖安装: `npm install -g typescript ts-node`，运行命令: `ts-node client_example.ts [args...]`
+
+### cURL 示例 (Linux/macOS)
+
+您也可以使用 `curl` 和其他命令行工具直接触发回调。这是一个一键执行的示例，它会自动从 `backup.conf` 读取密钥、生成签名并发起请求：
+
+```shell
+# 注意：请在 go/callback 目录下运行此命令
+SECRET=$(grep 'callback_secret' ../../backup.conf | cut -d '"' -f 2)
+BODY='{"args": ["-a", "--volumes"]}'
+SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
+
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "X-Signature: $SIGNATURE" \
+  -d "$BODY" \
+  http://localhost:47731/backup
+```
+
+## 文档导航
+
+- [完整使用指南 (USAGE.md)](USAGE.md)
+- [GitHub Actions 工作流文档 (WORKFLOW_zh-CN.md)](WORKFLOW_zh-CN.md)