Harbor

English · 简体中文

Self-hosted publishing hub for people who write in Chinese and publish everywhere. Write once, ship to fifteen platforms, and keep every published copy in sync — with AI drafting, a compliance gate, and a human in the loop when a platform fights back.

What it does

Related MCP server: Hashnode MCP Server v2.0

Screens

Fifteen adapters, each declaring what it can actually do. Greyed-out actions are not supported by that platform, not missing features.

Quick start

Requires Python 3.10+, uv, Node 20+ and pnpm.

git clone https://github.com/badhope/harbor.git
cd harbor

# Terminal 1 — backend
cd backed
uv sync
uv run uvicorn app.factory:create_app --factory --host 127.0.0.1 --port 8000 --reload

# Terminal 2 — frontend
cd web
pnpm install
pnpm dev            # http://127.0.0.1:5173

Open http://127.0.0.1:5173. The Vite dev server proxies /api to port 8000.

Desktop shell (experimental)

cd web
pnpm install
pnpm run tauri dev

Tauri launches the Python backend as a sidecar. Packaging is not verified across platforms — see Known limits.

Connect a platform

Two connection styles, decided per platform:

Browser login — for platforms without a usable API. Open Settings → Platform accounts, click Log in on the platform, and complete the scan or password step in the window that opens. The session is stored in a local profile and reused.

uv run --project backed python -m backed.cli --headed login --platform zhihu

Protocol credentials — for platforms with a stable API. Fill in platforms.<name> in config.json; no browser needed. See PLATFORM_CONNECTION.md for the field list per platform.

uv run --project backed python -m backed.cli publish --id <article-id> --platforms zhihu,juejin

Configuration

Edit backed/config.json, or use environment variables:

Deployment

Docker Compose runs the backend behind nginx, with the token injected server-side:

export SECRET_KEY=$(openssl rand -hex 32)
export HARBOR_API_TOKEN=$(openssl rand -hex 32)
docker compose -f deploy/docker-compose.yml --profile web up -d --build

The backend is not exposed to the host; nginx terminates and injects the token. Data lives in the hub_data volume.

Testing

bash scripts/check_all.sh          # all gates; Linux/macOS
pwsh -File scripts/check_all.ps1   # all gates; Windows

cd backed && uv run pytest -q      # backend only
pnpm --dir web test                # frontend only

check_all runs eight gates: compileall, ruff, version consistency, secret scan, pytest, eslint, vitest, vite build.

Architecture

Vue 3 SPA  ──REST/SSE──►  FastAPI  ──►  Publishing hub
(Tauri shell)             (uvicorn)      ├── 15 platform adapters
                                         ├── task engine + scheduler
                                         ├── SQLite (WAL + FTS5)
                                         └── MCP bridge (stdio/SSE)

Details in docs/architecture/ARCHITECTURE.md.

Known limits

Read this before trusting any claim above.

• Browser fetch and screenshot are enabled but network-restricted. The target host is pinned to its validated public IP inside Chromium and every sub-resource is checked. Private, loopback and link-local targets are rejected.

• Real publishing is not regression-tested against live platform DOM. Adapters pass a static contract probe; only Juejin has a captured DOM sample. Verify with a draft before relying on any platform.

• Docker and Tauri builds are unverified on this machine. Docker daemon unavailable; Tauri fails with a local linker error. The compose file and sidecar script exist but have not produced a tested artifact here.

• No auto-update, no signed release manifest, no cross-platform installer.

Documentation

License

MIT — see LICENSE.