📦 OGP Expose — 公网暴露OGP

安全说明 隧道是可选的——而且通常比其他方案更私密。 ogp expose 使用 cloudflared 或 ngrok 为 OGP daemon 创建一个安全的公网 URL。这只是其中一种做法，并非唯一做法。你可以按自己的喜好暴露网关： - Cloudflared/ngrok 隧道（默认）——你的真实 IP 永远不会暴露；流量通过隧道服务商的基础设施中转 - 反向代理（nginx、Caddy 等）——如果你有一台拥有固定 IP 的服务器 - VPN/Tailscale——仅与同一网络内的节点联邦 - 任何可公开访问的 URL——手动更新 ~/.ogp/config.json 中的 gatewayUrl 隧道方案作为零配置便利提供。除非你明确运行 ogp install（它会先创建 LaunchAgent/systemd 服务并先征求确认），否则不会安装任何常驻服务。 ## 前置条件 必须先安装 OGP daemon。如果看到类似 'ogp: command not found' 的错误，请先安装： ``bash npm install -g @dp-pcs/ogp ogp-install-skills ogp setup ` 完整文档：https://github.com/dp-pcs/ogp # OGP Expose - 公网隧道设置 本技能帮助通过 cloudflared 或 ngrok 隧道将 OGP daemon 暴露到互联网。 ## 何时使用 在以下场景使用本技能： - 用户希望让 OGP daemon 可被公开访问 - 用户需要用于联邦的公网 URL - 用户想为 OGP 设置隧道 - 用户正在远程测试 OGP 联邦 ## 前置条件 ### 使用 Cloudflared（推荐） 安装 cloudflared： `bash # macOS（Homebrew） brew install cloudflared # Linux wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 sudo mv cloudflared-linux-amd64 /usr/local/bin/cloudflared sudo chmod +x /usr/local/bin/cloudflared # Windows # 下载地址：https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ ` ### 使用 ngrok 安装 ngrok： `bash # macOS（Homebrew） brew install ngrok/ngrok/ngrok # Linux/Windows # 下载地址：https://ngrok.com/download ` 在 https://ngrok.com 注册并获取你的 auth token： `bash ngrok config add-authtoken ` ## 用法 ### 使用 Cloudflared 暴露（默认） `bash ogp expose ` 这会： 1. 在 daemon 端口启动 cloudflared 隧道 2. 显示公网 URL（例如 https://abc-def-123.trycloudflare.com） 3. 保持隧道运行，直到你手动停止（Ctrl+C） 更新配置： `bash # 编辑 ~/.ogp/config.json # 将 "gatewayUrl" 设为 cloudflared 显示的 URL ` ### 使用 ngrok 暴露 `bash ogp expose --method ngrok ` 这会： 1. 在 daemon 端口启动 ngrok 隧道 2. 显示公网 URL（例如 https://abc123.ngrok-free.app） 3. 在 http://127.0.0.1:4040 打开 ngrok Web 界面 更新配置： `bash # 编辑 ~/.ogp/config.json # 将 "gatewayUrl" 设为 ngrok URL ` ## 完整设置流程 ### 首次设置 1. 运行 OGP 设置： `bash ogp setup ` - 输入临时网关 URL（后续会更新） 2. 启动 daemon： `bash ogp start ` 3. 在新终端暴露 daemon： `bash ogp expose ` 4. 复制 cloudflared/ngrok 显示的公网 URL 5. 更新配置： `bash # 编辑 ~/.ogp/config.json # 更新 "gatewayUrl": "https://your-tunnel-url" ` 6. 重启 daemon： `bash # 在 daemon 终端用 Ctrl+C 停止 ogp start ` 7. 验证设置： `bash # 在另一终端或浏览器测试： curl https://your-tunnel-url/.well-known/ogp ` ### 使用 Cloudflared 命名隧道的永久设置 生产环境建议创建永久 cloudflared 隧道： `bash # 登录 cloudflared tunnel login # 创建隧道 cloudflared tunnel create ogp-daemon # 记下显示的隧道 ID # 创建配置文件：~/.cloudflared/config.yml cat > ~/.cloudflared/config.yml < credentials-file: ~/.cloudflared/.json ingress: - hostname: ogp.yourdomain.com service: http://localhost:18790 - service: http_status:404 EOF # 运行隧道 cloudflared tunnel run ogp-daemon ` ## 对比：Cloudflared vs ngrok ### Cloudflared 优点： - 免费、不限流量 - 临时隧道无需注册 - 快速稳定 - 可创建带自定义域名的永久隧道 缺点： - 每次重启 URL 会变化（除非使用命名隧道） - 永久隧道需要 Cloudflare 账号 ### ngrok 优点： - Web 界面 http://127.0.0.1:4040 - 可查看与重放请求 - 付费版支持自定义域名 - 付费版提供固定 URL 缺点： - 免费版有限制 - 需要注册 - 免费版 URL 会变化 - 免费版有流量/并发限制 ## 故障排查 ### 隧道无法启动 - 找不到 Cloudflared： 安装 cloudflared - 找不到 ngrok： 安装 ngrok 并配置 auth token - 端口已被占用： 停止占用 18790 端口的其他服务 ### 无法访问公网 URL - 检查防火墙设置 - 确认 daemon 正在运行（ogp status） - 先在本地测试：curl http://localhost:18790/.well-known/ogp ### 隧道频繁断开 - 检查网络连接 - 改用永久隧道而非临时隧道 - 考虑将隧道作为系统服务运行 ## 作为系统服务运行 ### macOS（launchd） 创建 ~/Library/LaunchAgents/com.ogp.tunnel.plist： `xml Label com.ogp.tunnel ProgramArguments /usr/local/bin/cloudflared tunnel --url http://localhost:18790 RunAtLoad KeepAlive ` 加载服务： `bash launchctl load ~/Library/LaunchAgents/com.ogp.tunnel.plist ` ### Linux（systemd） 创建 /etc/systemd/system/ogp-tunnel.service： `ini [Unit] Description=OGP Cloudflared Tunnel After=network.target [Service] Type=simple User=youruser ExecStart=/usr/local/bin/cloudflared tunnel --url http://localhost:18790 Restart=always [Install] WantedBy=multi-user.target ` 启用并启动： `bash sudo systemctl enable ogp-tunnel sudo systemctl start ogp-tunnel `` ## 安全提示 - 隧道会将 OGP daemon 暴露到互联网 - 只有经过批准的节点才能发送消息（签名验证） - 所有消息均经过加密签名 - 生产环境建议启用 IP 白名单 - 仅使用 HTTPS 隧道（cloudflared/ngrok 已自动处理）