구조와 기능

Postiz 는 여러 SNS 채널에 글을 예약해 올리고 반응을 모아 보는 셀프호스트 도구다. 저장소는 pnpm 모노레포이고 apps/ 아래에 backend, frontend, orchestrator, extension, sdk, commands 가 나뉘어 있다.

채널 연동은 libraries/nestjs-libraries/src/integrations/social/ 에 모여 있다. 이 폴더의 provider 파일은 36개이고, 스레드·인스타·틱톡·유튜브·링크드인·X·블루스카이·마스토돈 같은 채널이 각각 한 파일을 차지한다. 링크드인 페이지, 틱톡 비즈니스처럼 같은 채널의 변형도 별도 파일이다.

예약 실행은 Temporal 워크플로가 맡는다. apps/orchestrator/src/workflows/ 에 게시·토큰 갱신·누락 게시·미디어 처리 워크플로가 있고, 게시 워크플로는 post-workflows/ 안에 v1.0.1 부터 v1.1.2 까지 판이 쌓여 있다. 이미 돌고 있는 예약이 새 코드에 깨지지 않게 판을 남기는 Temporal 의 관행을 따른 것이다.

• 셀프호스트 docker-compose.yaml 이 띄우는 이미지: 앱 본체, Postgres 두 개, Redis, Elasticsearch, Temporal 서버·관리도구·UI, Sentry Spotlight. 모두 9개.
• 의존성: dependencies 214개, devDependencies 58개.

AI 쪽은 Mastra 기반 MCP 서버(libraries/nestjs-libraries/src/chat/start.mcp.ts)다. chat/tools/ 에 게시 예약, 게시 목록, 미디어 업로드, 이미지·영상 생성 같은 도구가 있어 에이전트가 직접 예약을 걸 수 있다. 저장소 루트에는 ChatGPT 앱 제출용 chatgpt-app-submission.json 과 에이전트용 CLAUDE.md 도 있다.

하이라이트

스레드 게시는 상태를 확인한 뒤에 올린다

Threads API 는 컨테이너를 만들고, 미디어 처리가 끝나면 publish 하는 두 단계다. Postiz 는 그 사이에 컨테이너 상태를 계속 묻는다(threads.provider.ts 의 checkLoaded).

// Bounded (the old version recursed forever and could hang the activity
// into a timeout): ~5.5 minutes at 2.2s intervals.
for (let i = 0; i < 150; i++) {
  const status = await this.checkContainerStatus(mediaContainerId, accessToken);
  if (status === 'FINISHED' || status === 'PUBLISHED') { await timer(2000); return true; }
  await timer(2200);
}

주석에 따르면 예전 판은 끝없이 재귀하다 작업이 시간 초과로 멈췄고, 지금은 횟수를 정해 두고 끝내면서 이유를 사람이 읽을 문장으로 돌려준다. ERROR·EXPIRED 를 따로 잡아 「미디어 형식을 확인하라」고 안내하는 것도 같은 함수 안에 있다.

채널마다 같은 모양의 메서드

provider 파일은 인증 URL 만들기, 토큰 갱신, 게시, 댓글, 지표를 같은 이름의 메서드로 맞춘다. 스레드 파일을 보면 댓글은 reply_to_id 로 이어 붙이고, 지표는 threads_insights 에서 views·likes·replies·reposts·quotes 를 하루 단위로 받는다. 채널 하나를 더할 때 손대는 곳이 파일 하나로 끝나는 구조다.

주의점

라이선스는 AGPL-3.0 이다. 고쳐서 남에게 서비스로 내면 고친 소스를 공개해야 한다. 외부 기여에는 FLA 2.1(CCLA.md·ICLA.md) 서명을 받는다.

실측한 테스트 파일은 0개다. jest.config.ts 는 있지만 *.spec.ts·*.test.ts 가 하나도 없다. 최근 90일 커밋이 738건인 속도에 비하면, 업그레이드 때 회귀를 막아 줄 안전망이 저장소 안에 보이지 않는다.

운영 부담이 크다. 혼자 쓰는 예약 도구에 Temporal 과 Elasticsearch 까지 띄워야 하고, 이미지 태그가 latest 라 고정하지 않으면 재시작 때 판이 바뀔 수 있다. ChatGPT 앱 제출 문서는 지원 채널을 「28+」로 적고 있어, 실제 provider 파일 수와 소개 문구가 서로 다르다.

실측 정보

GitHub 스타 / 포크

40,045 / 7,586

오픈 이슈

214건 (최근 25건 중 8건 응답, 중앙값 16.7시간)

커밋 / 최근 90일

3,489건 / 738건 (전체 이력, 2024-01-26 ~ 2026-10-28)

참여 저자 / 원격 태그

74명 / 206개

파일 / 텍스트 줄 수

1,036개 / 226,596줄 (ts 77,923 · tsx 52,969)

테스트 파일 / CI 워크플로

0개 / 9개

라이선스

AGPL-3.0 (기여 시 FLA 2.1 서명)

사이트 실측

주소

postiz.com

응답 · 첫 화면

200 · 5.5초 (데스크톱)

요청 · 전송량

121개 · 3.2MB

깨진 요청 · 콘솔 오류

0개 · 0개

폰(390px)

가로 넘침 없음

디자인

어두운 화면 · __DM_Sans_0d7163 · __Plus_Jakarta_Sans_646807

홈페이지를 실제 크롬으로 띄워 첫 화면까지만 쟀습니다(2026-10-29 · 데스크톱 1440px · 폰 390px). 로그인 · 입력 같은 동작은 하지 않았고, 사이트 상태는 리포 품질과 따로 봅니다. 색 칸은 바탕 · 면 · 글자 · 흐린 글자 · 강조 · 선, 점선은 「못 잼」.

적용점

• P0 · 비용 낮음스레드 미디어 게시는 컨테이너 상태가 FINISHED 가 될 때까지 확인한 뒤 publish 한다. 고정 대기(sleep)로 게시하는 스크립트라면 이 확인 고리만 옮겨도 간헐적 실패가 줄어든다
• P1 · 비용 중간채널 하나를 provider 파일 하나로 두고 인증·게시·댓글·지표를 같은 모양의 메서드로 맞춘 구조는 채널을 늘릴 때 그대로 본뜰 만하다
• P2 · 비용 높음AI 에이전트용 MCP 서버(Mastra)로 예약·미디어 업로드를 열어 둔 방식은, 사람 승인 게이트를 어디에 둘지 함께 설계할 때만 참고한다

원문 README

아래는 gitroomhq/postiz-app 저장소의 README 원문입니다(GitHub 렌더, 수집 시점 기준). 저작권은 원 프로젝트에 있으며 원 저장소의 라이선스를 따릅니다. GitHub에서 보기

README 전문 펼치기

Postiz is a social media management platform for scheduling, automating, and analyzing your content.

Use Postiz Cloud for a fully managed experience, or deploy the open-source edition on your own infrastructure.

Explore the docs »

Watch the YouTube Tutorials»

Register · Join Our Discord (devs only) · Public API

NodeJS SDK · N8N custom node · Make.com integration

Schedule posts to:

With your favorite AI agent:

🔌 See the leading Postiz features

✨ Features

Our Sponsors

Sponsor	Logo	Description
Hostinger		Hostinger is on a mission to make online success possible for anyone – from developers to aspiring bloggers and business owners
Virlo		Virlo is the #1 social media trend spotting and all-in-one GTM tool for teams leveraging short-form video
ChatbotX		The ManyChat alternative that you can self-host, white-label, and resell to your clients. Bring your own OpenClaw, Hermes, or Claude agents!
RapidProxy		RapidProxy provides 90M+ residential IPs for social media, browser automation, and AI workflows, with smart rotation and stable sessions. From $0.55/GB; use RAPID10 for 10% off.

Intro

• Schedule all your social media posts (many AI features)
• Measure your work with analytics.
• Collaborate with other team members to exchange or buy posts.
• Invite your team members to collaborate, comment, and schedule posts.
• Perfect for automation (API) with platforms like N8N, Make.com, Zapier, etc.

Tech Stack

• Pnpm workspaces (Monorepo)
• NextJS (React)
• NestJS
• Prisma (Default to PostgreSQL)
• Temporal
• Resend (email notifications)

Quick Start

To have the project up and running, please follow the Quick Start Guide

Sponsor Postiz

We now offer a few options to sponsor Postiz:

• Just a donation: You like what we are building, and want to buy us some coffee so we can build faster.
• Main repository: Get your logo with a backlink from the main Postiz repository. Postiz has over 7M downloads and 20k views per month.

Link: https://opencollective.com/postiz

Postiz Cloud vs. Open-source

Choose Postiz Cloud for a fully managed experience, or deploy Postiz Open-source on your own infrastructure. Both provide the same core Postiz product and features.

We do not "gate" features or limit the license.

The main difference is the infrastructure you need to own, approval from social media providers, and deployment that might be hard at times (let your LLM deploy it)

Area	Postiz Cloud	Postiz Open-source (self-hosted)
Cost	Subscription per plan, 7-day free trial	Free forever (AGPL-3.0); you pay only for your own infra
Setup time	Sign up and connect channels in minutes	Deploy with Docker / Coolify / Railway / any VPS; you configure Postgres, Redis, storage and env vars
Hosting & data	Hosted by Postiz; data stored in our infrastructure	Runs on your own server; data never leaves your environment
Social platform apps	Pre-approved apps for every channel, ready to use	You create your own developer apps on each platform and go through their approval (Meta, YouTube, TikTok can take weeks)
Channels	Limited by plan tier	Unlimited, every supported provider
Posts per month	Limited by plan tier	Unlimited
Team members	Limited by plan tier	Unlimited
Scheduling, calendar views, cross-posting, repeated posts, post comments & delays, sets, signatures	Included	Included
Internal & Global Plugs, RSS auto-post, customer groups	Included per plan	Included
Analytics	Included per plan	Included (requires your own app credentials with analytics scopes)
AI Copilot, AI images, AI videos	Included with monthly quotas per plan; keys managed by Postiz	Available if you bring your own OpenAI (and other provider) API keys; no quota, you pay the provider
AI video clipping	Included with monthly clipping minutes per plan	Requires your own provider keys and extra configuration
Smart Agent	Included per plan	Available with your own LLM key
Public API & webhooks	Included per plan	Included
Agentic surfaces (MCP, CLI, Claude / ChatGPT / Codex / OpenClaw / Cursor connectors)	Included, hosted MCP endpoint	Included, you point the MCP / CLI at your own instance
Custom integrations	Included per plan	Included; you can also modify the code and add providers
Updates & maintenance	Automatic, zero downtime for you	You pull new images and run migrations yourself
Uptime, backups, security patches	Managed by Postiz	Your responsibility
Support	Priority support via Discord / email per plan	Community support on Discord and GitHub
Source access & customization	No (SaaS)	Full source code, fork and modify freely under AGPL
Compliance / data residency	Postiz-controlled regions	Any region or air-gapped environment you choose

Postiz Compliance

• This GitHub repository contains the open-source, self-hosted edition of Postiz. Postiz is also available as Postiz Cloud, a fully managed service at postiz.com.
• Postiz hosted service uses official, platform-approved OAuth flows.
• Postiz does not automate or scrape content from social media platforms.
• Postiz does not collect, store, or proxy API keys or access tokens from users.
• Postiz never asks users to paste API keys into our hosted product.
• Postiz users always authenticate directly with the social platform (e.g., X, Discord, etc.), ensuring platform compliance and data privacy.

License

This repository's source code is available under the AGPL-3.0 license.

의견

판정에 대한 반론, 도입 경험, 정정 제보를 환영합니다. GitHub 계정으로 참여합니다.