开发者文档

# 在服务器上安装并注册为被控端
curl -fsSL https://get.ggremote.com/agent | sh

ggremote-agent register \
  --token gr_agent_**************** \
  --name "prod-db-01" \
  --tags "env=prod,role=db" \
  --unattended            # 允许无人值守访问（会提示设置独立密码）

# 确认状态
ggremote-agent status
# → {"device_id":"dev_8f31c7","status":"online","peers":0}

- hosts: db_servers
  become: true
  vars:
    ggremote_token: "{{ vault_ggremote_token }}"
  tasks:
    - name: 安装 ggremote agent
      ansible.builtin.shell: curl -fsSL https://get.ggremote.com/agent | sh
      args:
        creates: /usr/local/bin/ggremote-agent

    - name: 注册为被控端
      ansible.builtin.command:
        cmd: >
          ggremote-agent register
          --token {{ ggremote_token }}
          --name {{ inventory_hostname }}
          --tags "env=prod,role=db"
          --unattended --password-stdin
      args:
        stdin: "{{ vault_unattended_password }}"
      register: reg
      changed_when: "'already registered' not in reg.stdout"

# 1. 拉取部署文件
curl -fsSL https://get.ggremote.com/selfhost | sh

# 2. 配置域名、证书与授权
cat > .env <<'EOF'
GGREMOTE_DOMAIN=remote.your-company.com
GGREMOTE_LETSENCRYPT_EMAIL=ops@your-company.com
GGREMOTE_LICENSE=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
GGREMOTE_TURN_SECRET=$(openssl rand -hex 32)
EOF

# 3. 启动
docker compose up -d

# 4. 验证
curl https://remote.your-company.com/healthz
# → {"status":"ok","version":"3.4.1","peers":0,"relay_region":"internal"}

# Windows: %ProgramData%\ggremote\config.json
# macOS:   /Library/Application Support/ggremote/config.json
# Linux:   /etc/ggremote/config.json
{
  "server": "remote.your-company.com",
  "port": 443,
  "fallback_public": true,
  "telemetry": false
}

import requests

BASE = "https://api.ggremote.com/v1"
HEADERS = {"Authorization": "Bearer gr_live_****************"}

# 1. 找出所有生产环境的在线设备
devices = requests.get(
    f"{BASE}/devices",
    headers=HEADERS,
    params={"tags": "env=prod", "status": "online"},
    timeout=10,
).json()

for d in devices["data"]:
    print(d["id"], d["name"], d["last_seen"], d["quality"]["latency_ms"])

# 2. 为某台设备创建会话令牌（客户端用这个令牌发起连接）
session = requests.post(
    f"{BASE}/devices/dev_8f31c7/session",
    headers={**HEADERS, "Idempotency-Key": "req-20260911-001"},
    json={"mode": "control", "record": True, "ttl_seconds": 300},
    timeout=10,
).json()

print(session["data"]["token"])          # 供客户端 SDK 使用
print(session["data"]["recording_id"])   # 本次会话的录像 ID

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask 示例：必须用原始 body，不能先 json.loads 再序列化
@app.post("/ggremote/webhook")
def hook():
    if not verify(request.get_data(), request.headers["X-GGR-Signature"], SECRET):
        return "", 401

    event = request.json
    if event["type"] == "session.started":
        notify_security_team(event["data"])   # 含发起人、目标设备、来源 IP
    return "", 204

{
  "request_id": "req_3a91bd0c72",
  "error": {
    "code": "ApprovalRequired",
    "message": "设备 prod-db-01 已启用连接审批，需主管批准",
    "retryable": false,
    "details": { "approval_id": "apr_71c3f9", "policy": "high-risk-devices" }
  }
}