self-hosted-social-scheduler
Postiz/self-hosted social: Docker+DB+API debugging.
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- self-hosted-social-scheduler
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "postiz", "social-media", "docker", "postgresql", "debugging", "instagram", "tiktok", "oauth" ], "related_skills": [ "systematic-debugging" ] } }
- platforms
- [ "linux" ]
- description
- Postiz/self-hosted social: Docker+DB+API debugging.
02 资源文件 1
- 参考文档references/postiz-debug-20260922.md2.5 KB
03 SKILL.md 正文
Self-Hosted Social Scheduler Debugging
Overview
Diagnose posting failures on self-hosted social media schedulers (Postiz, Buffer, etc.) that run in Docker with PostgreSQL. The canonical flow is:
- Confirm the service is running and healthy
- Inspect config (docker-compose for API keys, tokens)
- Check container logs for upstream timeouts and social API errors
- Query the DB directly for post state, error messages, and integration status
- Interpret social API error codes
Always do these before suggesting the user re-authenticate — the DB tells the real story.
Step 1: Service Health
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}\t{{.Status}}" | grep postiz
curl -s -o /dev/null -w "%{http_code}" http://localhost:4007
A 307 redirect is normal (SSR app). A 200 or 502 tells you backend status.
Step 2: Configuration Inspection
read_file /opt/postiz/docker-compose.yaml
Key env vars: MAIN_URL, FRONTEND_URL, INSTAGRAM_APP_ID/SECRET, TIKTOK_CLIENT_ID/SECRET, JWT_SECRET, NOT_SECURED.
Step 3: Container Logs
# Get recent errors (filter /api/mcp scanner noise)
docker logs --tail 100 postiz 2>&1 | grep -iv "upstream timed out" | grep -iE "error|fail|instagram|tiktok|facebook|oauth|token"
Step 4: Database Introspection
Connect
cat << 'SQL' | docker exec -i postiz-postgres sh -c 'psql -U postiz-user -d postiz-db-local'
-- SQL here
SQL
For multi-line queries, write a temp file inside the container to avoid shell quoting issues:
docker exec postiz-postgres sh -c "cat > /tmp/q.sql << 'SQL'
SELECT ... FROM \"Table\";
SQL
psql -U postiz-user -d postiz-db-local -f /tmp/q.sql"
Discover columns first — Postiz uses camelCase
SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = 'Post' ORDER BY ordinal_position;
Key Tables
User:
SELECT id, email, name, "createdAt" FROM "User" ORDER BY "createdAt" DESC;
Integration (connected social accounts):
SELECT id, name, type, profile, "providerIdentifier", "refreshNeeded"
FROM "Integration" ORDER BY "createdAt" DESC;
providerIdentifier= platform (instagram-standalone,tiktok,facebook,x)refreshNeeded=truemeans token expired, needs re-auth
Post (scheduled/published/failed):
SELECT id, title, state, "publishDate", "integrationId"
FROM "Post" ORDER BY "publishDate" DESC NULLS LAST LIMIT 20;
state:QUEUE= scheduled,PUBLISHED= done,ERROR= failed,DRAFT= draft- Join on
integrationIdto get platform
Errors (JSON failure traces):
SELECT id, message, "createdAt" FROM "Errors" ORDER BY "createdAt" DESC LIMIT 5;
The message column is a JSON blob from Temporal. Parse details[0].json for the actual API error payload.
Cross-reference posts with platforms
SELECT p.id, p.title, p.state, p."publishDate", i."providerIdentifier"
FROM "Post" p
LEFT JOIN "Integration" i ON p."integrationId" = i.id
ORDER BY p."publishDate" DESC NULLS LAST;
Step 5: Social API Error Patterns
Instagram / Facebook — "API access blocked" (OAuthException code 200)
Meaning: Meta revoked/blocked the access token. Common causes:
- Token expired (60-day lifetime for Instagram)
- Password changed → all tokens invalidated
- App disconnected from Instagram Settings
- Instagram professional account status changed
Fix: Re-authenticate in Postiz UI (Integrations → Instagram → Disconnect & Reconnect).
Quirk: Earlier queued posts may show PUBLISHED while later ones fail — the token was valid when queued, then expired.
TikTok — "App not approved for public posting"
Error: unaudited_client_can_only_post_to_private_accounts
Meaning: The TikTok developer app hasn't passed TikTok's audit. Unaudited apps can only post to private/self-view accounts.
Fix: Submit the app for review in TikTok Developer Portal. Not fixable in Postiz config.
TikTok — "url_ownership_unverified"
Error: PULL_FROM_URL rejected by TikTok's API.
Meaning: TikTok does not support URL-based media transfer for unaudited apps. The image bytes must be uploaded directly.
Fix: Use DIRECT_POST instead of PULL_FROM_URL, or wait for TikTok app audit.
Upstream Timeouts (Nginx → Backend)
Log: upstream timed out (110: Connection timed out)
Meaning: Node.js backend (port 3000) hung. Often from slow third-party API calls or DB query issues.
Diagnosis:
docker logs postiz 2>&1 | grep -v "upstream timed out" | grep -v "/api/mcp"
Pitfalls
column does not exist: Postiz uses camelCase. Always quote:"createdAt"notcreated_at. When piping through bash, heredoc with'END'(single-quoted delimiter) works.- Docker logs are noisy: Scanners hit
/api/mcp. Always filter them out. - Token ≠ App keys: The
docker-compose.yamlshows app Client ID/Secret, not user tokens. User tokens are in the DBIntegration.token/refreshToken. - "Instagram worked for some posts, not others": Token was valid when those were queued. Check error timestamps vs post creation times.
- Psql inside docker exec:
cat | docker exec -i postgres sh -c 'psql ...'is reliable. For complex queries, write to a temp file first.
04 同仓库更多 Skills
writing-plans
Write implementation plans: bite-sized tasks, paths, code.
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
subagent-driven-development
Execute plans via delegate_task subagents (2-stage review).
plan
Write a markdown plan to .hermes/plans/; no execution.
hermes-agent-skill-authoring
Author in-repo SKILL.md files: frontmatter and structure.
debugging-hermes-tui-commands
Debug Hermes TUI slash commands: Python, gateway, Ink UI.