douyin-bridge

douyin-bridge

Local backend for a Douyin profile downloader. Runs a real browser on your machine so profile crawls use your session and your IP.

npx douyin-bridge --login   # once — sign in
npx douyin-bridge           # every time you download

Then open the web UI and point it at http://127.0.0.1:8788.

---

Why this exists

Listing a Douyin profile's posts requires an authenticated, non-headless browser session. That session has to live somewhere, and the options are:

• on a shared server — every visitor's crawl runs as one account, which gets rate-limited and banned, and attributes all activity to whoever hosts it;
• on your own machine — your account, your IP, nothing shared.

This is the second one. The hosted UI never sees your credentials.

What it does

Speaks three routes, identical to the hosted API:

Route	Purpose
POST /api/resolve	share link → sec_uid
POST /api/posts	crawl the profile's post list
POST /api/download	stream media bytes from Douyin's CDN

/api/posts drives a real Chromium to the profile and listens to the API responses the page itself makes. The page signs its own requests, so there is no a_bogus signature to forge and nothing to break when ByteDance rotates it.

Options

--port <n>            Port to listen on            (default 8788)
--allow-origin <url>  Extra origin allowed to call this bridge
                      (localhost and *.vercel.app are always allowed)
--login               Just log in, then exit
--profile <dir>       Browser profile directory
                      (default ~/.douyin-bridge/profile)

You must log in

Douyin serves anonymous visitors ~21 posts and a login wall, then stops. The page never requests more, so no amount of scrolling helps — and 21 posts looks exactly like a small profile unless you check.

Measured against a real 475-post profile while signed out:

作品 (posts) : 475
captured     : 21

Run npx douyin-bridge --login, click 登录, scan the QR with the Douyin app. The session persists in ~/.douyin-bridge/profile, so this is a one-time step.

Note this browser profile is separate from your normal Chrome — being logged in there does not carry over.

After each crawl the bridge compares what it captured against the 作品 count on the profile page. If it comes up short the result is flagged as partial, and the UI says so rather than presenting a truncated archive as complete.

Security

• Only localhost, *.vercel.app, and any --allow-origin you pass may call the bridge. Other origins get 403, so a random site you visit cannot use your machine as a Douyin proxy.
• /api/download is allow-listed to Douyin CDN hostnames, so it cannot be turned into a general-purpose open proxy.
• Binds to 127.0.0.1 only — never exposed to your network.

Notes

• First run downloads Chromium (~150 MB). After that startup is instant.
• Keep the terminal open while crawling and downloading.
• Headless mode does not work: Douyin serves headless clients nothing.

Licence

MIT. Downloads only what a profile already makes public. Respect Douyin's Terms of Service and creators' rights.