Postiz 登录与鉴权配置：获取 API Key 并连接 CLI
Postiz 是社媒排期工具，用 API Key 或 OAuth2 授权 CLI。截至 2026 年 8 月 13 日，官方 CLI 文档仍以设备授权为推荐路径，并保留 API Key 与自托管地址配置；现在配置时应先判断使用的是官方托管版还是自托管版，再选对应的鉴权方式。
下文中的操作、路径和命令均来自官方文档或官方仓库；跨文档对照或适用边界会明确标注，不把经验判断写成官方结论。
先分清：Postiz 的“登录”有两种
Postiz 的“登录”容易混为一谈。第一种是仪表盘登录：用浏览器进入 Postiz 控制台，查看内容、账号设置和集成；第二种是程序鉴权：让 CLI、SDK、n8n、Make.com 或脚本获得 API 访问权限。
程序鉴权又有两种凭证：
- OAuth2：官方 CLI 文档标注为推荐方式，通过浏览器完成设备授权，凭证保存在本机。
- API Key：从控制台的
Settings → API Keys生成，之后通过Authorization请求头发送。
官方还提供了 Postiz API 鉴权说明 和 Postiz CLI 鉴权文档。两者用途不同：前者用于公共 API 请求，后者专门讲 CLI 的登录、状态检查、退出和环境变量。
下表可以直接决定该走哪条路径：
| 使用场景 | 推荐方式 | 凭证放在哪里 | 适合谁 |
|---|---|---|---|
| 只想在终端使用 Postiz CLI | OAuth2 设备授权 | ~/.postiz/credentials.json |
不想手动复制密钥的人 |
| 调用公共 API | API Key | Authorization 请求头或 POSTIZ_API_KEY |
写脚本、接自动化的人 |
| 自托管 Postiz，并使用自建接口 | API Key 加自定义 URL | POSTIZ_API_URL |
私有化部署的运维或开发人员 |
| 同时存在 OAuth2 与 API Key | OAuth2 | 本机凭证文件优先 | 已经在 CLI 中完成设备授权的人 |
这里最关键的选择是：日常用 CLI 就先做 OAuth2 登录；程序集成或无浏览器环境再准备 API Key。官方 CLI 文档明确说明，两种凭证同时存在时，OAuth2 credentials take priority over the API key。
开始前：只检查这 3 项
-
确认使用哪个 Postiz 地址。 官方托管版通常使用
https://api.postiz.com；自托管版需要填写自己的 API 地址。运行postiz auth:status查看当前状态，再核对控制台入口。 -
准备浏览器和控制台权限。 API Key 只能在登录后的
Settings → API Keys中生成，因此需要能进入对应账户；浏览器授权时还要能打开授权页面。 -
确认是否接入收费方案。 官方文档没有把生成 API Key 或 CLI 鉴权列为单独收费项；托管版账户方案、云服务费用与自托管服务器成本不在这套鉴权流程内。
路径一：用 OAuth2 登录 CLI
OAuth2 是官方 CLI 文档推荐的方式。它使用设备授权流程，不需要在终端中手动填写客户端 ID（Client ID，应用身份标识）或密钥。
在终端执行：
postiz auth:login按官方文档描述，这条命令会完成三件事：
- 在终端显示一次性代码；
- 打开浏览器，让用户确认授权；
- 自动把凭证保存到
~/.postiz/credentials.json。
浏览器授权完成后，不要立刻退出终端。执行下面的命令检查凭证是否仍然有效：
postiz auth:status成功标志不是“终端没有报错”这么简单，而是 postiz auth:status 能确认当前凭证有效。此时再次运行 API 或集成操作时，不再需要手动导出 POSTIZ_API_KEY。
需要撤销本机凭证时，执行：
postiz auth:logout该命令会移除已经保存的凭证。退出后如果还要继续使用 CLI，重新运行 postiz auth:login 即可。
路径二：获取 API Key 并放入请求
需要使用公共 API、Node.js SDK 或其他程序化集成时，进入 Postiz 控制台，按以下路径操作：
Settings → API Keys → Generate New API Key
生成后复制 API Key，并把它保存在密码管理器或密钥管理系统中。不要提交到 Git 仓库，也不要发到公开文档、截图或聊天记录里。官方 API 鉴权文档明确提醒，API Key 拥有账户的完整访问权限。
调用公共 API 时，把密钥放进 Authorization 请求头：
curl https://api.postiz.com/public/v1/integrations
-H "Authorization: YOUR_API_KEY"
-H "Content-Type: application/json"如果使用 Node.js SDK，官方示例采用以下形式：
const postiz = new Postiz('YOUR_API_KEY');
const integrations = await postiz.integrations();SDK 会自动处理鉴权请求头。复制代码时必须同时替换占位符 YOUR_API_KEY，但不要把真实密钥写进公开仓库。源码仓库的官方入口是 gitroomhq/postiz-app，README 将其定位为可自行部署的社交媒体管理与排期项目，并提供公共 API、Node.js SDK、n8n 与 Make.com 集成入口。
自托管版：密钥和地址要成对设置
如果 Postiz 部署在自己的服务器上，默认 API 地址通常不适用。官方 CLI 文档列出了三个相关环境变量：
| 环境变量 | 是否必需 | 默认值 | 用途 |
|---|---|---|---|
POSTIZ_API_KEY |
OAuth2 登录后不需要 | 无 | API Key 鉴权 |
POSTIZ_API_URL |
否 | https://api.postiz.com |
自托管 API 地址 |
POSTIZ_AUTH_SERVER |
否 | https://cli-auth.postiz.com |
自托管鉴权服务器地址 |
API Key 模式可以这样设置：
export POSTIZ_API_KEY=your_api_key_here
export POSTIZ_API_URL=https://your-postiz-api.example.com
export POSTIZ_AUTH_SERVER=https://your-auth-server.example.com这里三个地址都是示例，实际值应替换为自己的部署域名。如果自托管环境没有单独的鉴权服务器，不要为了“配齐”而填写不存在的 POSTIZ_AUTH_SERVER；只设置实际使用的地址。
还要注意环境变量的作用范围。上面使用的是 export，通常只对当前终端会话有效。关闭窗口后变量会消失，这是安全上的正常行为；若脚本或定时任务依赖该变量，应在运行任务的执行环境中注入，而不是把密钥硬编码进脚本。
容易卡住的地方：先判断是哪一层失败
Postiz 鉴权涉及浏览器、控制台、CLI 和 API 服务，界面看起来相似，但故障并不在同一层。
授权后仍被识别为未登录。 如果浏览器切换了账号或另一个标签页结束会话，GitHub 官方登录页会出现这类原文提示：You signed in with another tab or window. Reload to refresh your session. 这属于 GitHub 会话状态问题，不是 Postiz API Key 失效。处理方式是刷新当前页面，再从 Postiz 官方仓库 返回项目。
GitHub 登录页加载失败。 官方登录页可能显示：There was an error while loading. Please reload this page . 先刷新页面；仍无法进入时，使用 GitHub 密码重置入口 检查账号，或通过 GitHub 注册入口 确认所用邮箱。
OAuth2 与 API Key 同时存在。 这不是冲突：官方 CLI 文档规定 OAuth2 凭证优先。执行 postiz auth:status 查看当前使用的是哪一份；需要完全改回 API Key 时，先执行 postiz auth:logout 移除本机 OAuth2 凭证，再设置 POSTIZ_API_KEY。
自托管请求打错服务。 API 请求地址和鉴权服务器不是同一个概念：前者接收业务 API 请求，后者处理 CLI 的 OAuth2 授权。分别设置 POSTIZ_API_URL 与 POSTIZ_AUTH_SERVER，不要把两者互相替代。
怎么算配置成功
完成鉴权后，用三个可观察结果验收：
- 运行
postiz auth:status，能确认当前凭证有效； - 执行公共 API 的
curl请求后，接口能够返回集成列表，而不是鉴权失败； - 使用自托管版时，请求实际进入自己的 API 服务，而不是默认的
https://api.postiz.com。
如果采用 API Key，还应检查环境变量是否在即将运行命令的那个终端或任务环境中生效。密钥已经复制，并不等于程序一定能读取到它；常见的边界判断是：先执行 postiz auth:status，再执行实际 API 请求，两层都通过才算配置完成。
官方入口与后续维护
配置期间优先使用以下一手入口：
- Postiz CLI 鉴权文档：查看 OAuth2、状态检查、退出和三个环境变量。
- Postiz API Authentication：查看 API Key 的生成位置、
Authorization请求头和 SDK 示例。 - Postiz 官方 GitHub 仓库：查看源码、部署入口、Public API、Node.js SDK 以及自动化集成说明。
- LobeHub 的 Postiz 技能说明：可用于交叉核对 CLI 凭证文件路径和 OAuth2 优先级；具体命令仍以 Postiz 官方 CLI 文档为准。
升级 CLI 或修改部署架构后，应重新执行 postiz auth:status。如果状态失效，再按官方流程重新登录或重新生成 API Key，而不是把旧密钥继续复制到更多位置。
评论区
登录后可评论。