wx_channels_download 的 Cloudflare 部署命令（deploy）实战指南：一键部署公众号 RSS、视频号查询与 Bridge 桥接 Worker

• 桌面应用
• 视频
• 网络
• MCP 服务

wx_channels_download 是一套集视频号、公众号内容抓取与下载于一体的工具。当你需要把公众号 RSS/API、视频号视频查询页面或 Bridge 桥接服务托管到 Cloudflare 时，无需手工登录 Dashboard 逐个创建 Worker、D1 数据库或 Pages 项目——内置的deploy命令会读取本地配置文件，通过 Cloudflare REST API 完成全部部署。读完本文，你将掌握deploy mp、deploy sph、deploy bridge三条子命令的配置字段、前置权限、部署产物与可用 API，并能理解每条命令背后的源码实现逻辑。

本文以 docs/cli/deploy.md 为骨架，结合仓库源码（入口见 cmd/deploy.go，各 Worker 部署实现见 internal/workers/mp/deploy.go、internal/workers/sph/deploy.go、internal/workers/bridge/deploy.go）进行扩充。

deploy 命令概览：一个父命令，三条子命令

deploy是一个父命令，本身不执行任何部署动作，必须指定二级命令。其 CLI 注册位于 cmd/deploy.go，通过 cobra 挂载了mp、sph、bridge三个子命令：

wx_video_download deploy <command>

三个子命令都从配置文件（默认config.yaml）读取参数，通过viper获取对应配置项后调用各自的Deploy函数，全程通过 Cloudflare REST API 完成，无需本地安装 wrangler。命令执行期间会以 spinner 形式输出各阶段进度；成功后打印部署摘要（Worker 名称、ID、URL 等），失败时给出明确的权限或配置提示。

前置条件与通用配置

无论部署哪个 Worker，都需要先具备：

• 一个 Cloudflare 账号，并取得Account ID和API Token；
• API Token 需包含Workers 相关的读写权限（Workers Scripts:Edit）；
• 部署公众号 Worker 时，还需D1 数据库相关权限（D1:Edit）；
• 部署 Bridge 时，还需Pages:Edit权限。

通用的 Cloudflare 配置项如下（配置文件模板见 internal/config/config.template.yaml）：

cloudflare: accountId: "your-cloudflare-account-id" apiToken: "your-cloudflare-api-token"

Account ID 与 API Token 是所有子命令的必填项。在源码层，各Deploy函数都会在normalize_deploy_options阶段对这两个值做TrimSpace后校验非空，缺任一项会直接返回未配置 cloudflare.accountId/未配置 cloudflare.apiToken错误（例如 internal/workers/mp/deploy.go）。

deploy bridge：部署 Durable Objects 桥接 Worker 与 Pages 管理页面

deploy bridge一次部署两个部分：用于桥接/转发远程调用的Durable Objects Bridge Worker，以及受密码保护的Pages 管理页面。

wx_video_download deploy bridge

部署完成后的设备注册、调用 Token 创建、API 协议和多语言示例请参阅 Bridge 使用。

bridge 的配置

cloudflare: accountId: "your-cloudflare-account-id" apiToken: "your-cloudflare-api-token" bridge: deploy: workerName: "dm-bridge" pagesProjectName: "" # 留空时使用 dm-bridge-admin token: "bridge-client-token" adminToken: "bridge-admin-token"

这里bridge.deploy.token与bridge.deploy.adminToken必须使用不同的高强度随机值。源码在 internal/workers/bridge/deploy.go 中强制校验：两者都不可为空，且不能相同（bridge.deploy.adminToken 不能与 bridge.deploy.token 相同）。pagesProjectName留空时，默认取workerName + "-admin"（即dm-bridge-admin）。

部署流程与失败语义

命令会依次执行（对应 internal/workers/bridge/deploy.go 中的Deploy函数）：

1. 上传 Worker：通过 pkg/cloudflare/durableobjects/deploy.go 上传bridge.js主模块，配置名为BRIDGES的 Durable Object 绑定（类名BridgeDurableObject，存储后端为 SQLite），并把bridge.deploy.token、bridge.deploy.adminToken分别写入BRIDGE_TOKEN、BRIDGE_ADMIN_TOKEN两个 secret；
2. 启用并解析 workers.dev 子域：调用 Cloudflare API 为 Worker 启用 workers.dev 路由并查询账户子域名，拼出最终访问地址；
3. 构建管理页面静态资源：执行internal/workers/bridge/admin/build.sh，产出 Pages 的dist目录；
4. 创建或更新 Pages 项目：把BRIDGE_ADMIN_TOKEN配置为 Pages Secret，并建立指向该 Worker 的BRIDGEService Binding；
5. 上传管理页面静态资源和高级模式 Worker：Pages 目录中的_worker.js以高级模式部署，作用于全部路由。

任一步骤失败都会停止后续部署；如果 Pages 阶段失败，命令会明确提示Worker 已经部署成功，不会回滚 Worker（cmd/deploy.go中打印“Bridge Worker 已部署；请根据上面的 Pages 构建或 API 错误处理后重试”）。部署成功后，cmd/deploy.go会输出包含 Worker URL、健康检查地址（/health）、管理页面地址、管理 API（/admin/api/overview）、WebSocket 地址（/v1/connect）在内的完整摘要表，并提示把 URL 与bridge.deploy.token写入每台设备的bridge.url与bridge.token，管理页面使用用户名admin和bridge.deploy.adminToken登录。

Bridge 的角色与本地 API

从 internal/workers/bridge/README.md 可以完整了解 Bridge 的定位：一个 Bridge 由一个人管理，是连接外部调用方与多台操作系统设备的桥接/转发服务。它把统一的method + args调用转发给合适的在线设备，只保存调用参数、结果和下载元数据，不代理或保存视频文件。任务采用“至少一次投递”：分配时创建 120 秒租约，执行设备定期续租，连接中断后租约过期的任务会重新排队。

设备侧配置示例：

bridge: enabled: true url: "https://dm-bridge.<account>.workers.dev" deviceId: "mayfair-macbook" deviceName: "Mayfair MacBook" token: "<BRIDGE_TOKEN>" httpTimeoutSeconds: 30 methods: "auto"

• deviceId在当前 Bridge 内必须唯一且稳定，留空时程序使用系统主机名，生产环境建议显式设置；
• deviceName是管理页显示名称，留空同样使用主机名；
• methods是通用方法白名单：auto发布全部已注册方法，none只允许发布调用而不执行远程调用，也可填写逗号分隔列表（如wxchannels.fetch,wxchannels.contact.feed.list,download.create）。

本地状态接口为GET /api/bridge/status，返回当前设备到个人 Bridge 的连接状态。管理页面每 5 秒刷新展示设备，支持查看设备最近 7 天的连接/调用/心跳等事件日志，并可创建、充值、设定期限、移除调用 Token。调用 Token 明文只在创建时显示一次，Bridge 仅保存其 SHA-256 摘要；Token 过期或移除后新请求立即返回401。

deploy mp：部署公众号 RSS/API Worker

deploy mp用于部署公众号 RSS/API 相关的 Cloudflare Worker，适合把公众号订阅内容转成 RSS 或通过 REST API 拉取。

wx_video_download deploy mp

mp 的配置

cloudflare: accountId: "your-cloudflare-account-id" apiToken: "your-cloudflare-api-token" workerName: "mp-rss-api" d1Name: "mp-rss-db" refreshToken: "refresh-token" adminToken: "admin-token" mp: remoteServer: hostname: "your-remote-server-hostname"

模板中的默认值为workerName: "mp-rss-api"、d1Name: "mp-rss-db"（见 internal/config/config.template.yaml）。注意部署 mp 时 API Token 需要Workers Scripts:Edit 与 D1:Edit权限。

部署内容与 D1 迁移机制

部署内容（对应 internal/workers/mp/deploy.go）：

• 部署嵌入internal/workers/mp/index.js的 Worker（//go:embed index.js）；
• 执行嵌入internal/workers/mp/migrations/的 D1 迁移（//go:embed migrations/*.sql，实际迁移文件为internal/workers/mp/migrations/0001_init.sql）；
• 注入 D1 绑定DB，以及ADMIN_TOKEN、REFRESH_TOKEN、REMOTE_SERVER三个环境变量（均为plain_text绑定）。

D1 数据库的处理逻辑值得注意：当配置了d1Name时，命令先调用 D1 API 按名称查找数据库；找不到则自动创建；随后验证数据库连接并执行迁移。迁移采用自建的d1_migrations记录表（CREATE TABLE IF NOT EXISTS d1_migrations (...)），按文件名前缀的数字 ID 增量执行，已执行过的迁移会跳过（见 internal/workers/mp/deploy.go）。如果迁移失败，命令不会中止部署，而是把MigrationWarning放入部署结果并在成功输出中提示。若既未配置d1Name也未配置d1Id，部署会直接报错拒绝执行。

公众号 Worker 的可用 API

其中/api/mp/refresh需要 Refresh Token，/admin/token/*需要 Admin Token，/rss/mp通过biz参数指定公众号（这些细节同样体现在 cmd/deploy.go 部署成功后打印的 API 列表中）。

deploy sph：部署视频号查询 Worker

deploy sph把视频号视频信息查询页面部署为 Cloudflare Worker，提供 Web 界面查询视频号视频的下载地址。

wx_video_download deploy sph

注意：文档明确警告不要提供给外部使用，仅自己使用即可，有被限制使用 yuanbao 的风险。

sph 的配置

cloudflare: accountId: "your-cloudflare-account-id" apiToken: "your-cloudflare-api-token" sphWorkerName: "worker-name" sphCookie: "元宝 web 端 cookie" sphCredential: "页面及 API 的访问凭证"

元宝 Web 端指https://yuanbao.tencent.com/网站：登录后获取cookie填入sphCookie即可。元宝 Web 端 Cookie 有效期约1 个月，失效后需要重新登录获取新的 Cookie，并到 Cloudflare Worker 更新COOKIE环境变量。

源码对必填项的校验更严格（internal/workers/sph/deploy.go）：除 Account ID、API Token、Worker 名称外，sphCredential也是必填项，未配置时部署命令会直接拒绝（未配置 cloudflare.sphCredential）。

部署内容

• 部署嵌入internal/workers/sph/worker.js的 Worker（//go:embed worker.js）；
• 同时上传嵌入的internal/workers/sph/index.html和build/icon.png（图标会先被 base64 编码为一个icon.jsES 模块再随 multipart 上传）；
• Cookie 以COOKIE环境变量注入 Worker，用于调用视频号接口时的身份认证；
• 访问凭证以ACCESS_CREDENTIAL环境变量注入 Worker。

访问认证

浏览器访问 Worker 时会显示HTTP Basic Auth 登录框。用户名固定为wxchannels，密码填写cloudflare.sphCredential。登录后，页面对同源 API 的请求会自动携带认证信息。认证逻辑在 internal/workers/sph/worker.js 中实现：页面与静态资源公开，/api/*路径必须认证；Worker 未配置ACCESS_CREDENTIAL时返回503，凭证不匹配返回401。凭证校验通过 SHA-256 摘要比对完成，不传输明文。

直接调用 API 时可使用 Bearer Token：

curl -H 'Authorization: Bearer <sphCredential>' \ -H 'Content-Type: application/json' \ -d '{"url":"https://weixin.qq.com/sph/example"}' \ 'https://<worker-name>.<subdomain>.workers.dev/api/fetch_video_profile'

也可使用 Basic Auth：curl -u 'wxchannels:<sphCredential>' ...。

视频号查询 Worker 的可用 API

除 CORS 预检（OPTIONS）请求外，以上 API 均需认证；认证失败返回401，Worker 未配置ACCESS_CREDENTIAL时返回503。其中/api/fetch_video_profile的实现链路（见 internal/workers/sph/worker.js）分两步：先用元宝 Web 端接口解析分享链接得到wx_export_id与播放地址中的token/eid，再调用微信视频号预览接口get_feed_info拉取视频详情；/api/download_feed_zip则会把图集图片与 BGM 抓取后由 Worker 内实现的纯 JS ZIP 打包器生成压缩包返回。

部署命令的底层实现：Cloudflare REST API 封装

三条子命令最终都通过仓库内置的 Cloudflare API 客户端完成上传，这些客户端位于 pkg/cloudflare 下：

• pkg/cloudflare/worker/deploy.go：Workers Scripts Upload API 封装。以multipart/form-data上传 ES 模块（包含metadata与主模块、附加文件），支持配置兼容日期、Bindings、Exports；PutSecret写入 secret，EnableSubdomain启用 workers.dev 路由，GetSubdomain查询账户子域名以拼出最终 URL；
• pkg/cloudflare/pages/deploy.go：Pages Direct Upload 封装。EnsureProject保证项目存在并写入 Secret 与 Service Binding，随后校验并上传静态资源、创建生产部署；若目录含_worker.js则以 Pages 高级模式部署，并自动补齐默认路由规则；
• pkg/cloudflare/durableobjects/deploy.go：Bridge 专用，负责创建/更新 Durable Object 命名空间与 SQLite 存储绑定。

所有 HTTP 请求都使用Authorization: Bearer <apiToken>头访问https://api.cloudflare.com/client/v4，请求头、超时、multipart 构造与错误解析均由这些客户端统一处理，这也是命令无需本地 wrangler 的原因。

常见问题与排错思路

结合源码中的校验与错误分支，可归纳以下排错要点：

• 未配置 cloudflare.accountId/未配置 cloudflare.apiToken：先检查config.yaml中通用 Cloudflare 配置是否填写、是否有多余空格；
• 部署 mp 报 D1 相关错误：确认 API Token 包含D1:Edit权限；源码在 D1 API 返回7500或SQLITE_AUTH错误时，会额外提示“请检查 Account → D1:Edit 权限及数据库所属账户”（internal/workers/mp/deploy.go）；
• 部署 bridge 报adminToken 不能与 token 相同：两个 Token 必须是不同的高强度随机值；
• 部署 sph 被拒绝：cloudflare.sphCredential为必填项，未配置时命令不会执行部署；
• Bridge Pages 阶段失败但 Worker 已成功：命令不会回滚 Worker，按输出中的错误处理后重新执行命令即可（重复部署会更新代码并保留 Bridge 的设备登记与任务数据）；
• sph 查询失效：元宝 Web 端 Cookie 约 1 个月过期，重新登录后在 Cloudflare 控制台更新 Worker 的COOKIE环境变量即可。

小结

wx_video_download deploy把公众号 RSS/API（mp）、视频号查询页面（sph）、Bridge 桥接服务（bridge）三条 Cloudflare 部署链路统一收敛为一条本地命令。使用时只需在 internal/config/config.template.yaml 基础上填写 Account ID、API Token 及各业务专用配置，命令即可按阶段完成 Worker 上传、secret/绑定注入、D1 迁移、Pages 部署与 workers.dev 地址解析，并在终端输出完整的部署摘要与可用 API 列表。部署完成后，公众号 Worker 的接口见上文 API 表，Bridge 的设备注册、调用 Token 与调用协议参见 docs/feature/bridge.md，视频号查询页面则直接通过浏览器或 curl 使用即可。

• 桌面应用
• 视频
• 网络
• MCP 服务