Ydisks-Xianyu-Helper

Ydisks Xianyu Helper

An Xianyu multi-account management, messaging, and automated-delivery system built with Go and React.

English documentation · 中文 README · English Wiki · 中文 Wiki · Contributing · Security policy · Code of Conduct · License

The English Wiki is the default operational guide. The Chinese Wiki is available for the primary Chinese-speaking Xianyu community.

[!IMPORTANT] This project is for personal technical learning and research only. It has no official authorization from Xianyu or Alibaba.

This is an unofficial community tool and has no affiliation, partnership, or authorization relationship with Xianyu, Alibaba Group, or their affiliates.

Use it only in compliance with applicable law, platform rules, and the scope of your account authorization. Users are solely responsible for all consequences of using this code; the author assumes no responsibility.

If the platform requests that this project be taken down, it may be deleted or archived at any time.

Do not restart the program frequently while accounts are logged in. Every restart requests login credentials from Xianyu, and repeated requests may trigger risk controls.

Overview

Ydisks Xianyu Helper is a self-hosted management system for Xianyu sellers. It combines account runtimes, instant messaging, orders, products, card inventory, automation rules, AI replies, and exception notifications in one web console. It is intended for individuals and small teams managing multiple Xianyu accounts or delivering virtual goods.

The Go client implements Xianyu login, Cookie renewal, MTOP requests, and the WebSocket message path. QR login, face-verification flows, message connections, credential renewal, and most business logic are handled by the Go client. Chromium is used for features that require a browser environment.

Use with Ydisks Referral Assistant

If you promote Xianyu products through cloud-drive resources, tutorials, or digital packages, you can use Ydisks Referral Assistant alongside this project. Create separate short links for products, channels, or promotion accounts, then inspect PV, UV, trends, rankings, and channel/account reports in the Ydisks console.

Ydisks identifies where visits and conversion leads come from, while this project handles account messages, orders, and automated delivery. See the Ydisks Referral Assistant guide to create links and view data.

Use cases

• Unified online status and message management for multiple Xianyu accounts
• Automated delivery of digital goods, redemption codes, links, or images
• Paid delivery, staged bargain free shipping, review gifts, overdue review reminders, and unpaid-order price changes
• Product and order synchronization, list-based single- or multi-variant detection and publishing, and CSV/XLSX/TSV bulk listing with optional ZIP images
• Controlled AI customer service through OpenAI-compatible endpoints, with an end-to-end connection test

Community

Features

Module Capabilities Account management Multi-account start/stop, QR login, profile refresh, online status, login audit, and notes. Credential renewal Scheduled Cookie/token renewal, WebSocket credential updates, recovery, cooldowns, and failure disabling. Instant messaging Account-isolated chat, history, Xianyu emoji, text/images, official system-message recognition, keyword/default replies, and one-reply limits. Automation center Unpaid-order price changes, paid delivery, staged bargain free shipping, review gifts, review reminders, failure recovery, manual-intervention notifications, and idempotency checkpoints. Account tasks Event-driven automatic reviews based on locally recorded buyer-confirmed-receipt events, daily product refresh, manual execution, execution records, and idempotency protection. Card inventory Text, batch cards, images, and API delivery, with batch import, quantity, and delay settings. Product management Synchronization, manual association, list-card isSKU-based single- or multi-variant detection (missing or false means single-variant), publishing, image ordering, category lookup, and bulk listing. Delivery templates Ordered multi-message delivery and order, buyer, card, and custom variables. Orders Synchronization, editing, platform delivery, card resending, and exception handling. AI replies OpenAI-compatible APIs, model discovery, end-to-end connection testing, custom prompts, bargaining rounds, and discount limits. Notifications Bark, DingTalk, Feishu, WeCom, Telegram, email, and custom Webhooks. Storage and security SQLite/MySQL/PostgreSQL, embedded Goose migrations, AES-256-GCM sensitive-field encryption, log redaction, and outbound-address validation. Container deployment PostgreSQL 17, health checks, persistent volumes, and multi-architecture GHCR images.

Architecture

flowchart LR
    UI["React admin console"] --> API["Go / chi HTTP API"]
    API --> Store["SQLite / MySQL / PostgreSQL"]
    API --> Manager["Account manager"]
    Manager --> Engine["Per-account runtime"]
    Engine --> WS["Xianyu WebSocket"]
    Engine --> MTOP["Xianyu MTOP"]
    Engine --> Automation["Automation center"]
    Automation --> Notify["Notification channels"]
    Engine -. "browser capability" .-> Chromium["Playwright / Chromium"]

Core responsibilities:

• internal/composition: the single production composition root
• internal/application: use-case orchestration, ownership checks, transactions, and compensation
• internal/xianyu: login protocol, Cookies, MTOP, WebSocket, and message protocol
• internal/engine: per-account lifecycle, message handling, replies, and delivery
• internal/automation: delivery, review gifts, reminders, and scheduling
• internal/browser: Chromium automation, browser-fingerprint reading, and token slider capabilities
• internal/db: database access, encryption, dialect-specific migrations, and repositories
• internal/server: HTTP/SPA transport, management authentication, and embedded frontend assets

Screenshots

Quick start

Docker Compose (recommended)

Docker Compose supports Linux x86_64, Linux ARM64, and Apple Silicon. Docker Engine or Docker Desktop and Docker Compose v2 are required.

git clone https://github.com/Christ9038/Ydisks-Xianyu-Helper.git
cd Ydisks-Xianyu-Helper
cp .env.example .env

Set at least POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, DATABASE_URL, XIANYU_DATA_KEY, and XIANYU_ADMIN_PASSWORD in .env:

POSTGRES_DB=xianyu
POSTGRES_USER=xianyu
POSTGRES_PASSWORD=replace-with-a-strong-password
DATABASE_URL=postgres://xianyu:url-encoded-password@postgres:5432/xianyu?sslmode=disable
XIANYU_DATA_KEY=replace-with-a-long-lived-random-key
XIANYU_ADMIN_PASSWORD=replace-with-an-admin-password

Generate random values with:

openssl rand -hex 24
openssl rand -base64 48

Start the application and PostgreSQL:

docker compose up -d

Open http://localhost:59188 and sign in as admin with the configured administrator password. The Compose file uses persistent PostgreSQL, application-data, and browser-data volumes. Back up the database and .env before upgrading.

GHCR images can be pulled anonymously when public. If the image is private, log in to ghcr.io with a Personal Access Token that has read:packages permission.

Run from source

Requirements are Go 1.26.4 or compatible, Node.js 24 with npm, Chromium system dependencies, and optionally SQLite.

git clone https://github.com/Christ9038/Ydisks-Xianyu-Helper.git
cd Ydisks-Xianyu-Helper
npm --prefix frontend ci
npm --prefix frontend run build
go run ./cmd/server -db data/xianyu_data.db -addr 127.0.0.1:59188

When the database has no administrator, the first visit shows the initialization form. For headless or operational environments:

go run ./cmd/server -init-admin -db data/xianyu_data.db -admin-password 'replace-with-a-strong-password'

The frontend is embedded at build time through Go go:embed. Restart the Go service after rebuilding it.

Desktop packages

Desktop packages contain xianyu-server for the backend and Chromium, and xianyu-tray for the Windows tray or macOS menu bar. Packages include the matching Playwright driver and Chromium runtime; users do not need to download a second browser.

Platform Service Controller Data and logs Windows YdisksXianyuHelper Windows Service xianyu-tray.exe C:\ProgramData\YdisksXianyuHelper macOS com.ydisks.xianyu-helper.server LaunchAgent Ydisks闲鱼助手.app menu-bar program ~/Library/Application Support/YdisksXianyuHelper and ~/Library/Logs/YdisksXianyuHelper Linux ydisks-xianyu-helper.service systemd unit No desktop tray /var/lib/ydisks-xianyu-helper and /var/log/ydisks-xianyu-helper

Windows and macOS controllers show checking, starting, healthy, and stopping states; they can control the backend and open the log directory. Exiting the controller stops the backend first. Linux installation must run install.sh as root on the matching architecture and uses systemd. Uninstall retains /var/lib/ydisks-xianyu-helper by default.

Formal releases provide Windows, macOS arm64/amd64, and Linux amd64/arm64 packages. Release tags use v1.2.3 format and must point to main. The release workflow builds and tests every native architecture, launches Chromium, checks /health, waits for production-release Environment approval, and then publishes packages, SHA256SUMS, Docker tags, and a GitHub Release. Windows and macOS signing requires the configured certificate Secrets; Linux does not.

Local macOS packaging:

npm ci --prefix frontend
npm run build --prefix frontend
mkdir -p dist/macos/arm64
go build -trimpath -ldflags='-s -w' -o dist/macos/arm64/xianyu-server ./cmd/server
go build -trimpath -ldflags='-s -w' -o dist/macos/arm64/browser-install ./cmd/browser-install
go build -trimpath -ldflags='-s -w' -o dist/macos/arm64/xianyu-tray ./cmd/tray
packaging/macos/build-pkg.sh 0.0.0-local "$PWD/dist/macos" arm64

The packaging script prepares matching runtime files from the local Playwright cache when needed. Use amd64 for Intel macOS. Without a signing identity, the result is an unsigned pkg.

The desktop first-run URL is http://127.0.0.1:59188. Set and confirm the administrator password in the web page. Source examples using -addr :59188 listen on all interfaces; restrict the port with a firewall, security group, or reverse proxy. Use -no-browser only when Chromium is unavailable; browser-fingerprint and token-slider features will then be unavailable.

First use

1. Sign in as administrator.
2. In Account Management, scan the QR code with the Xianyu app.
3. Complete face or security verification only through the official flow.
4. Wait until the account is online, then sync products and orders.
5. Create delivery content in Card Inventory.
6. Associate products, cards, specifications, and triggers in Automation.
7. Use Chat to inspect history and test text, emoji, or image messages.
8. Configure automatic reviews and daily refresh under Account Management; if needed, enable the independent bargain free-shipping switch for the “bargain pending” stage (it does not replace automatic delivery or shipment confirmation).
9. Configure keyword replies, default replies, AI replies, and notifications as needed.

The Go client currently supports QR login only. Do not share Cookies, passwords, QR codes, or verification URLs.

Configuration

Database connection precedence is:

DATABASE_URL > -db-url > -db

Important environment variables:

Variable Default Description