MediaX

README

MediaX

简介

MediaX 是一个支持多平台内容发布的轻量级 SDK，旨在帮助开发者快速集成到主流自媒体平台，实现统一的内容发布接口。

ArisanCloud 团队已经成功维护了 PowerWechat 开源项目，基本上 SDK 的框架接口趋于稳定，所以我们有延伸出这个 MediaX，同时也做了模块优化， 按需加载模块，支持更多平台的接口使用。

MediaX 系列产品介绍

• MediaX：一个 开源的 Golang SDK，可以直接被其他项目引用。
• MediaX Studio：基于 MediaX 构建的商业化服务，包含 API（gRPC/HTTP）、高级功能和闭源插件，面向企业用户。

功能特点

1. 多平台支持：支持主流的自媒体平台如抖音、小红书，youtube 等。
2. 统一接口：通过标准化的接口，实现对多个平台的内容发布。
3. 开源与闭源结合：Studio 支持插件化架构，开源插件可自由扩展，闭源插件提供增强功能。
4. 跨语言支持：Studio 通过 gRPC 实现跨语言调用，支持 Go 和其他语言集成。
5. 可扩展性：灵活的 Provider 机制，轻松接入新平台。

MediaX 快速开始

环境要求

• Go 1.18 或更高版本

使用知识

• OAuth2.0 授权流程，可以参考理解 OAuth 2.0文章

安装

1. 初始化项目并下载 MediaX：

   go get github.com/ArtisanCloud/MediaX
   

2. 创建一个简单 客户端凭证模式（Client Credentials Grant）（非用户授权）的示例，本项目作者正在自己系统中使用，陆续会迭代版本：

   
   import (
      "github.com/ArtisanCloud/MediaX/pkg/client"
      config2 "github.com/ArtisanCloud/MediaX/pkg/client/config"
      "github.com/ArtisanCloud/MediaX/pkg/utils"
      "github.com/ArtisanCloud/MediaXCore/pkg/cache"
      "github.com/ArtisanCloud/MediaXCore/pkg/logger/config"
      "github.com/ArtisanCloud/MediaXCore/utils/fmt"
      "github.com/ArtisanCloud/MediaX/pkg/client/wechat/officialAccount/clientTokenClient/publish/schema"
      "github.com/redis/go-redis/v9"
   )
   
   // 配置Media Client实例的信息
   mediaXClient := client.NewMediaX(&config2.MediaXConfig{
     &config.LogConfig{
         Level:   "debug",
         Console: true,
         File: config.FileConfig{
             Enable: true,
         },
     },
   }, c)
   
   // 从MediaXClient实例中获取到微信平台中公众号的实例，该实例是Client Token模式，不需要用户授权
   wechatOAClient, err := mediaXClient.MediaXClient.NewWeChatOfficialAccountCTClient(&config2.WeChatOfficialAccountConfig{
     ClientConfig: &ClientConfig{
         BaseConfig: &BaseConfig{
            Timeout: 30,
            HttpDebug: true,
         },
         OAuthConfig: &OAuthConfig{
            ClientID: "your client/app id"
            ClientSecret: "your client/app secret"
         },
     },
   })
   if err != nil {
     panic(err)
   }
   
   // 调用 wechatOAClient 的方法
   ctx := context.Background()
   var reqData = &schema.DraftAddReq{}
   resData, err := oaClient.GetPublishClient().DraftAdd(ctx, reqData)
   if err != nil {
      return nil, err
   }
   
   

3. OAuth 2.0 授权码模式（Authorization Code Grant）（用户授权）的示例，本项目作者正在自己系统中使用，陆续会迭代版本：

   import (
      "github.com/ArtisanCloud/MediaX/pkg/client"
      config2 "github.com/ArtisanCloud/MediaX/pkg/client/config"
      "github.com/ArtisanCloud/MediaX/pkg/utils"
      "github.com/ArtisanCloud/MediaXCore/pkg/cache"
      "github.com/ArtisanCloud/MediaXCore/pkg/logger/config"
      "github.com/redis/go-redis/v9"
      "github.com/ArtisanCloud/MediaX/pkg/client/config"
      "github.com/ArtisanCloud/MediaX/pkg/client/google/youtube/accessTokenClient/video/schema"
      "github.com/ArtisanCloud/MediaXCore/utils/fmt"
      "github.com/ArtisanCloud/MediaXCore/utils/object"
   )
   
   googleYouTubeClient, err := mediaXClient.CreateGoogleYouTubeACClient(localConfig.GoogleYouTubeConfig)
   if err != nil {
   	panic(err)
   }
   
   // 设置AccessToken
   googleYouTubeClient.GoogleClient.TokenHandler.GetCustomToken = func(key string, refresh bool) object.HashMap {
   	fmt.Dump("GetCustomToken", key, refresh)
    return object.HashMap{
   		// 这个acess token需要开发这来维护，或者可以通过MediaX Studio的UI界面来维护
   		"access_token": "72_ggzUdSgH99StJ2EhmuaIbHHUP9_3rDvdnQVQ9eoX5gwmNfuLpJgBUb5uPgdoh4aoVv9jYz3EKglRT73ppWqgRwzirNQM-bHaToDQ83ux1sFdCr5GK7jxYQfAESoCOEaAHAKWM",
   		"expires_in":   float64(7200),
    }
   
   

Zhihu SessionToken 配置片段

在 config.yaml 中通过 session_token_providers 配置知乎 SessionToken，支持多 Provider/App/Mode：

session_token_providers:
  providers:
    - code: zhihu
      name: 知乎
      apps:
        - code: web
          name: 知乎 Web
          provider_code: zhihu_sessiontoken
          auth_modes:
            - key: default
              label: 默认
              zhihu_session_token_config:
                strategy: zhihu_pc_v1
                service:
                  base_url: http://127.0.0.1:7070
                  api_token: dev-session-token
                  timeout: 30
                  http_debug: false
                  api_version: v4
                authenticator:
                  entries:
                    - type: pc
                      url: https://www.zhihu.com/signin?next=%2F
                  default_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.6312.58 Safari/537.36
                  script_ids:
                    - sessiontoken.zhihu.auth.pc.v1
                  captcha_strategy: auto
                harvester:
                  watch_cookies:
                    - SESSIONID
                    - JOID
                    - osd
                    - q_c1
                    - d_c0
                    - unlock_ticket
                    - z_c0
                  watch_headers:
                    - X-XSRF-TOKEN
                  harvest_script_id: sessiontoken.zhihu.harvest.pc.v1
                callback:
                  secret: mediax-sessiontoken-callback
                  max_retry: 3
                  retry_backoff: [2, 4, 8]
                network:
                  proxy: ""
                  proxy_pool: zhihu-default
                  ip_strategy: china_rotating
                  request_timeout: 60
                api:
                  retry_backoff: [2, 4, 8]

若仓库首次拉取尚无 config.yaml，运行 make sessiontoken-bootstrap（或 ./scripts/sessiontoken-bootstrap.sh）即可从 config.example.yaml 复制上述默认模板，再按环境覆盖 callback secret/Redis 等字段。可配合 .env.example 统一维护调试所需的环境变量。

SessionToken 环境变量

本地/插件应保持以下环境变量一致，可直接复制 .env.example：

变量	说明	默认
SESSIONTOKEN_LISTEN_ADDR	SessionToken HTTP 服务监听地址	:7070
SESSIONTOKEN_API_TOKEN / POWERX_SESSION_TOKEN_API_TOKEN	Flow 接口鉴权	dev-session-token
POWERX_SESSION_TOKEN_BASE_URL	插件访问的 SessionToken Base URL	http://127.0.0.1:7070
POWERX_SESSION_TOKEN_CALLBACK_URL	插件自身的回调接口	https://plugin.local/api/v1/...
POWERX_SESSION_TOKEN_CALLBACK_SECRET	回调签名 secret，对应 callback.secret	mediax-sessiontoken-callback
SESSIONTOKEN_DEBUG_CALLBACK_URL	/debug 页面默认回调地址	http://127.0.0.1:7070/debug/callback
SESSIONTOKEN_REDIS_ADDR	Flow 存储 Redis	127.0.0.1:6379
SESSIONTOKEN_ZHIHU_PROXY	代理地址，覆盖 network.proxy（可填 none/direct 表示禁用代理；未设置时默认 none）	空
SESSIONTOKEN_ZHIHU_API_BASE_URL	可覆盖默认 https://www.zhihu.com	空
SESSIONTOKEN_ZHIHU_API_VERSION	强制指定 Zhihu API 版本（如 v4）	v4

启动 SessionToken HTTP 服务

1. 统一环境变量：确保 MediaX 与插件共用以下值（可写入 .env）：

   export POWERX_SESSION_TOKEN_BASE_URL="http://127.0.0.1:7070"
   export POWERX_SESSION_TOKEN_API_TOKEN="dev-session-token"
   export POWERX_SESSION_TOKEN_CALLBACK_URL="https://plugin.local/api/v1/admin/platforms/session-token/callback"
   

2. 启动服务：在 MediaX 仓库根目录运行 make sessiontoken（内部执行 go run ./cmd/sessiontoken -config config.yaml，默认监听 :7070）。
3. 启动插件：在插件或 MediaX Studio 侧，将 POWERX_SESSION_TOKEN_* 指向上一步的 BaseURL/API Token/Callback URL，再启动 /publish/platforms 等入口触发模拟登录。
4. 顺序要求：必须先启动 SessionToken 服务，待日志出现 sessiontoken: server listening... 后再启动插件/浏览器容器，否则插件会因无法访问 /session-token/flows 返回 5xx。

SessionToken 监控与排查

• 关注 sessiontoken_metric（Flow 创建/查询/完成）与 sessiontoken_callback（回调重试/成功）日志，字段中包含 provider/provider_app/tenant_uuid/flow_id/retry/latency_ms，便于将其采集到日志或指标系统实现 SLA 追踪。
• 快速排查可以直接 tail + ripgrep：

  tail -f logs/mediax.log | rg 'sessiontoken_(metric|callback)'
  

  典型日志：

  sessiontoken_metric: action=create_flow provider=zhihu provider_app=zhihu_article tenant_uuid=tenant_x account_id=acct_demo state=ui-flow flow_id=stf_xxx status=pending latency_ms=12 retry=0
  sessiontoken_callback: success provider=zhihu provider_app=zhihu_article tenant_uuid=tenant_x flow_id=stf_xxx state=ui-flow flow_status=succeeded retry=0 http_status=200 latency_ms=5
  

• 若 latency_ms 长期高于目标值，优先检查 Redis/第三方登录入口；若 retry >= 3，可结合 last_error 与插件回调响应定位网络问题。

本地调试与 Zhihu API 验证

• 浏览器访问 http://127.0.0.1:7070/debug 可使用调试台：Provider→App 级联、API Token/Callback 默认填入 dev-session-token + /debug/callback，所有输入会记忆在 localStorage。点击“创建 Flow”后会显示 Flow ID、authorize_url，并在 Mock 区域实时展示 /debug/callback 的最近 20 条记录。
• 手动写回 Cookie：授权页是普通浏览器标签页，需要手动在 DevTools Console 抓取 Cookie 并回传服务。典型流程：
  1. 在 /debug 创建 Flow 并复制 authorize_url，使用新的浏览器 profile 打开并完成知乎登录。
  2. 登录成功后在该标签页执行：

     (() => {
       const cookie = document.cookie;
       const pick = name => (new RegExp(`${name}=([^;]+)`)).exec(cookie)?.[1] || '';
       return {
         session_token: cookie,
         cookie_sessionid: pick('SESSIONID'),
         cookie_joid: pick('JOID'),
         cookie_osd: pick('osd'),
         cookie_q_c1: pick('q_c1'),
         cookie_d_c0: pick('d_c0'),
         cookie_unlock_ticket: pick('unlock_ticket'),
         cookie_z_c0: pick('z_c0'),
         credentials_note: navigator.userAgent
       };
     })();
     

  3. 将上一条的 JSON 通过 POST http://127.0.0.1:7070/debug/flows/<flow_id>/metadata 写回（可直接在 Console 中 fetch 发送）。服务端收到后会立即触发 harvester 并向 /debug/callback 推送成功记录。
• Playwright 自动调试器（可选）：项目内新增 tools/sessiontoken-browser/ CLI。首次运行时请在仓库根目录执行 pnpm install（或 npm install）以及 npx playwright install chromium 安装依赖/浏览器。随后即可使用 pnpm sessiontoken:browser --flow stf_xxx [--base http://127.0.0.1:7070] [--api-token dev-session-token]。若未显式提供 --api-token，会读取 SESSIONTOKEN_API_TOKEN/POWERX_SESSION_TOKEN_API_TOKEN 环境变量。脚本会：
  1. 调用 /session-token/flows/{flow_id} 解析 authorize_url。
  2. 通过 Playwright 拉起无痕 Chromium，自动打开上述 URL，提示你在弹出的窗口完成登录。
  3. 登录完成后脚本利用 CDP 读取 document.cookie 并调用 POST /debug/flows/<flow_id>/metadata 写回；终端中会显示 /debug/callback 返回的状态。
  4. 关闭窗口后即可在 /debug 页面刷新“Mock 回调”看到成功记录，再继续调用 zhihu/v1/* API。该 CLI 便于 QA 将整套流程脚本化，也可以在调试页里通过按钮提示用户运行。
• 如浏览器本身已处于登录状态，可勾选“复用 Cookie”选项，MediaX 会读取同租户/账号最近一次成功 Flow 的凭证并直接 succeeded，无需再次手动登录；若缓存缺失则自动回退到手动登录流程。
• API 调试面板（Beta）：/debug 页新增“API 调试”区块，会根据所选 Provider/版本（如 Zhihu v4）动态展示可调试的 Zhihu API（method/path/说明），并可一键复制示例 query/body。点击“从 Flow 填充 SessionToken”将调用 GET /session-token/flows/<flow_id> 自动填充 X-SessionToken，然后填写 query/path 参数并点“发送请求”即可直接调用 /zhihu/v1/*，响应会在页面下方实时展示。该面板默认携带 Authorization: Bearer <API Token>，也支持自行输入 session_token 以模拟失效流程。
• 终端快速调试可使用 scripts/sessiontoken-debug.sh：

scripts/sessiontoken-debug.sh flow stf_xxx
scripts/sessiontoken-debug.sh followings "$SESSION_TOKEN"
scripts/sessiontoken-debug.sh channels "$SESSION_TOKEN" zhihu_column_id 10 0
scripts/sessiontoken-debug.sh sanity "$SESSION_TOKEN"

其中 SESSION_TOKEN 取自 Flow metadata 或插件回调的 metadata.session_token 字段，脚本会自动读取 POWERX_SESSION_TOKEN_BASE_URL 及 API Token，并在安装 jq 时输出格式化 JSON。需要复用已有 Flow 时，可在本地执行 redis-cli --raw keys 'sessionToken:flow:*' 列出 key，再用 redis-cli --raw GET "sessionToken:flow:<id>" | jq '.' 查看 metadata，然后把 Flow ID 粘回 /debug 调试。 }

// 调用 Youtube的VideoClient 的方法 ctx := context.Background() video := googleYouTubeClient.GetVideoClient() res, err := video.List(ctx, &schema.YouTubeVideoListReq{}) if err != nil { panic(err) } fmt.Dump(res)

## 文档与接口说明

详细的功能接口文档和使用指南，请访问我们的[开发者中心](https://mediax.artisan-cloud.com)。在这里您可以找到:

- 完整的 API 参考文档
- 快速入门指南
- 最佳实践示例
- 常见问题解答

## 功能矩阵

| 平台     | 应用    | 授权类型          | 图文 | 视频 | 素材管理 | 评论管理 | 数据管理 |
| -------- | ------- | ----------------- | ---- | ---- | -------- | -------- | -------- |
| WeChat   | 公众号  | client_credential | ✔    | ✘    | ✔        | ✘        | ✘        |
| 小红书   | 聚光    | auth_code         | ✔    | ✔    | ✔        | ✘        | ✔        |
| 字节     | 抖音    | auth_code         | ✔    | ✔    | ✔        | ✔        | ✔        |
| 字节     | 抖音    | client_credential | ✔    | ✔    | ✔        | ✔        | ✔        |
| Bilibili | B 站    | auth_code         | ✔    | ✔    | ✔        | ✘        | ✔        |
| Google   | YouTube | auth_code         | ✔    | ✔    | ✔        | ✔        | ✔        |
| Google   | Blogger | auth_code         | ✔    | ✘    | ✘        | ✔        | ✔        |
| ......   |         |                   |      |      |          |          |          |

> 注：✔ 表示支持该功能，✘ 表示暂不支持该功能，🚧 表示功能开发中。

<!-- ## 功能介绍

\*\*\* [项目功能的开发安排](https://github.com/orgs/ArtisanCloud/projects/5/views/2) -->

## 产品主要维护者

Michael Hu

申请添加好友时，请备注产品名称，比如：“关注 MediaX”

<img src="https://mediax.artisan-cloud.com/assets/contact-qr-matrix-x.CMxSV8Gs.jpg" alt="请扫我" style="display:inline; width: 150px;"/>

## 许可证

MediaX SDK 项目 采用 [MIT License](./LICENSE) 开源。