Ydisks Xianyu Helper: a self-hosted Go and React stack for multi-account Xianyu delivery
闲鱼多账号自动发货、消息回复系统——基于 Go 与 React 构建
At a glance
- What is it?
- The project bundles account runtimes, WebSocket messaging, card inventory and automation rules behind one admin console. Its own README calls it an unofficial tool and warns that frequent restarts can trip platform risk controls.
- Who is it for?
- Adopt it only if you already sell virtual goods on Xianyu and accept that this is an unofficial tool the README says may be deleted or archived if the platform asks. Skip it if you need a vendor-backed integration, a supported SLA, or a tool that does not touch account credentials.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 18, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Ydisks Xianyu Helper actually replaces
Selling digital goods on Xianyu at any volume turns into a queue of manual steps. A buyer pays, you find the right redemption code, you send it, you mark the order, and you remember to ask for a review a week later. Multiply that by several accounts and the work becomes a rota. Ydisks Xianyu Helper is aimed at that rota: individuals and small teams running more than one Xianyu account, or delivering virtual goods where the fulfilment step is a string, a link or an image rather than a parcel.
The README lists the intended jobs plainly: unified online status across accounts, automated delivery of codes and links, paid delivery, staged bargain free shipping, review gifts, overdue review reminders, unpaid-order price changes, product and order synchronization, and CSV/XLSX/TSV bulk listing with optional ZIP images. That is a seller operations tool, not a marketplace scraper. The important framing is in the same file: the project states it has no official authorization from Xianyu or Alibaba, that it is an unofficial community tool, and that it may be deleted or archived if the platform requests it. Anyone evaluating this should read that paragraph before the feature table.
The Go client owns the protocol, React only draws the console
The split is visible in the repository layout. A React admin console talks to a Go HTTP API built on chi. Behind that API sits an account manager, and behind the manager a per-account runtime. Each runtime holds the Xianyu WebSocket connection and issues MTOP requests. The README states that QR login, face-verification flows, message connections, credential renewal and most business logic live in the Go client, with Chromium used only where a browser environment is required.
That last point matters more than it looks. Playwright and Chromium are dependencies, and the README describes internal/browser as handling Chromium automation, browser-fingerprint reading and token slider capabilities. So the browser is not decorative: some login and verification paths need it. The compose file defaults BROWSER_HEADLESS to true, which tells you the intended deployment is a headless container rather than a desktop session.
Storage is dialect-aware. The README lists SQLite, MySQL and PostgreSQL, embedded Goose migrations, AES-256-GCM encryption for sensitive fields, log redaction and outbound-address validation. The Makefile has a test-multidb target that fails outright when TEST_MYSQL_URL or TEST_POSTGRES_URL is missing, which suggests the maintainer treats three-dialect parity as a tested claim rather than an aspiration.
Installing from the GHCR image and logging in the first account
The default compose.yml is written for production deployment: it pulls a multi-architecture image from GHCR and does not build source on the server. Start by copying .env.example to .env. The example file requires COMPOSE_PROJECT_NAME, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, DATABASE_URL, XIANYU_DATA_KEY, XIANYU_ADMIN_PASSWORD and XIANYU_HTTP_PORT; the compose file marks DATABASE_URL, XIANYU_DATA_KEY and XIANYU_ADMIN_PASSWORD as mandatory with a Chinese error message if they are unset.
One detail in .env.example is easy to miss: if the database password contains special characters, it must be URL-encoded before it goes into DATABASE_URL. The example shows the shape of the value.
cp .env.example .env
# edit .env, then:
docker compose up -dThe app service runs /app/xianyu-server with -addr :59188 and -ensure-admin, and the port mapping defaults to 59188 on the host. The healthcheck queries http://127.0.0.1:59188/health and expects a 200. The README states that XIANYU_ADMIN_PASSWORD creates the admin account on the first docker compose up -d and that later restarts do not reset the password.
For a source build instead of the image, the Makefile exposes the entry points. The default build skips the integration build tag, so the browser package is not compiled in.
go build ./cmd/server
go build ./cmd/browser-installAfter the console is reachable, the account workflow is QR login from the account management page. The README is explicit about the operational rule here: do not restart the program frequently while accounts are logged in, because every restart requests login credentials from Xianyu and repeated requests may trigger risk controls. Treat restarts as an event to schedule, not a debugging habit.
Automation is checkpointed, but the failure paths are yours to watch
The automation center covers paid delivery, unpaid-order price changes, staged bargain free shipping, review gifts, review reminders, failure recovery, manual-intervention notifications and idempotency checkpoints. The account tasks module adds event-driven automatic reviews based on locally recorded buyer-confirmed-receipt events, plus daily product refresh and execution records.
Two environment variables in .env.example describe the safety nets. XIANYU_PENDING_SHIP_CATCHUP is on by default and covers the case where the payment system message is lost: it scans by order status to catch up on pending delivery and resumes unfinished pending-shipment runs. The comment states that two catch-ups for the same order are at least 10 minutes apart, and that resumption only releases idempotent finishing actions that will not contact the buyer again. Setting it to 0 disables both catch-up paths at once.
The second is XIANYU_CONTINUE_AFTER_UNCERTAIN, also on by default. When a message action's result is uncertain, it allows the chain to continue with confirm_shipment-only idempotent finishing actions. Setting it to 0 restores a full-chain circuit breaker.
These defaults deserve scrutiny. Both variables err toward completing the delivery rather than stopping, which is reasonable for a seller who would rather ship than leave a paid order hanging, and wrong for anyone who wants a hard stop whenever the platform's response is ambiguous. The README documents the switches but does not document what a partially completed delivery looks like to the buyer when the uncertain path is taken. That is a gap worth understanding from the execution records before you rely on it.
Where this is the wrong tool
The README's own warning is the first limitation: no affiliation, partnership or authorization with Xianyu or Alibaba, personal technical learning and research use only, and possible deletion or archival if the platform asks. If you need a supported integration with a vendor behind it, this is not that, and no amount of idempotency checkpointing changes the position you are in.
The second limitation is the credential model. The Go client performs login, holds Cookies and renews tokens on a schedule. That means account credentials and session material pass through your own infrastructure, protected by XIANYU_DATA_KEY and AES-256-GCM field encryption. Self-hosting is the selling point and the risk at the same time: you own the key, the database and the backups. Lose the key and the encrypted fields are gone with it.
The third is scope. This is a seller-side operations tool for Xianyu specifically. It does not help with other marketplaces, it does not replace an order-management system for physical inventory, and the browser dependency means a container that can run Chromium, which rules out the leanest hosting tiers.
Finally, the restart rule cuts against normal operational instincts. Rolling restarts, config reloads and container churn are routine elsewhere; here the README says repeated credential requests may trigger risk controls. Plan changes in batches.
Compared with writing your own client against the MTOP endpoints
The realistic alternative for a developer is not a competing product but a hand-rolled client: use the coder/websocket and go-openai dependencies, or their equivalents in another language, and wire up login, MTOP calls and a message loop yourself. The difference in approach is where the complexity lands.
A custom client gives you exactly the flows you need and no browser dependency, which matters if you never touch the face-verification or token slider paths. It also means you own every protocol change: when Xianyu alters a message shape or a login step, you are the one reading the diff. Ydisks Xianyu Helper absorbs that in internal/xianyu and internal/engine, and the release cadence shows the maintainer is still moving on it, with v1.0.13 published on 2026-09-17 and v1.0.12 two days earlier.
What you give up with the helper is control over the operational surface. The catch-up scans, the uncertain-result policy, the reply limits and the review-reminder timing are all decisions the project has already made for you, exposed as environment variables with defaults. A custom client lets you decide those yourself, at the cost of building the admin console, the card inventory, the delivery templates and the notification fan-out that this project already ships.
Licence, maintenance and the cost of staying current
The repository is licensed Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and NOTICE file and state your changes. Apache-2.0 also includes an explicit patent grant, which is a meaningful difference from a bare MIT licence if you plan to build on the code commercially. There is a NOTICE file at the repository root, so if you fork and redistribute, that file travels with you. This is a description of the licence terms, not legal advice; read LICENSE and NOTICE yourself.
On maintenance, the last push was on 2026-09-17, the same day as the v1.0.13 release, and the repository is not archived. That is the extent of what the repository metadata supports. There is no published roadmap in the repository, and the README does not document a rollback procedure for a failed upgrade, so the upgrade cost is mostly the cost of reading release notes and re-checking environment variables between versions.
The practical upgrade path is the compose file's pull_policy: always on the app service, which fetches the image on each start. That makes upgrading a matter of pulling and restarting, which collides directly with the README's warning about frequent restarts while accounts are logged in. Batch your upgrades. The database side is handled by embedded Goose migrations, so schema changes apply when the new binary starts, and the README does not describe a down-migration path.
Editorial conclusion
Adopt it only if you already sell virtual goods on Xianyu and accept that this is an unofficial tool the README says may be deleted or archived if the platform asks. Skip it if you need a vendor-backed integration, a supported SLA, or a tool that does not touch account credentials. Before deploying, read docs/wiki/Home.md, confirm what XIANYU_DATA_KEY does to existing rows if you change it, and check the login-audit page after the first QR login.
Frequently asked questions
How do I install Ydisks Xianyu Helper?
Copy .env.example to .env, fill in DATABASE_URL, XIANYU_DATA_KEY and XIANYU_ADMIN_PASSWORD, then run docker compose up -d. The default compose file pulls the multi-architecture image from GHCR rather than building source on the server.
Does Ydisks Xianyu Helper have official support from Xianyu or Alibaba?
No. The README states the project has no official authorization from Xianyu or Alibaba, that it is an unofficial community tool with no affiliation or partnership, and that it may be deleted or archived if the platform requests it.
Which databases can Ydisks Xianyu Helper use?
The README lists SQLite, MySQL and PostgreSQL, with embedded Goose migrations and dialect-specific migration files. The default compose.yml runs PostgreSQL 17 and the Makefile's test-multidb target requires both TEST_MYSQL_URL and TEST_POSTGRES_URL to run the three-dialect regression.
Community notes