Christ9038/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.

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.

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.

• 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

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

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.

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 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.

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.

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.

Database connection precedence is:

DATABASE_URL > -db-url > -db

Important environment variables:

Docker Compose also supports COMPOSE_PROJECT_NAME, POSTGRES_IMAGE, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, XIANYU_IMAGE, XIANYU_BIND_ADDRESS, and XIANYU_HTTP_PORT. Pin XIANYU_IMAGE to a release or SHA tag in production.

The main command-line options are -db, -db-url, -addr, -web, -workdir, -playwright-runtime-root, -playwright-driver-dir, -playwright-browser-dir, -data-key-file, -secure, -no-browser, -log-level, -log-format, -v, -init-admin, -ensure-admin, -admin-email, -admin-password, -service, and -version. See the Deployment and Database Wiki for detailed tables and examples.

The management console stores account state, automation, templates, reply rules, AI settings, bargaining strategy, notifications, logs, and administrator credentials in the database. Send data to external AI, SMTP, Webhook, or remote verification services only when their trust and data flow are understood.

The default image is multi-architecture:

ghcr.io/christ9038/ydisks-xianyu-helper:latest
├── linux/amd64
└── linux/arm64

The dev branch publishes dev and sha-full-commit tags. A v1.2.3 tag publishes v1.2.3, 1.2.3, 1.2, latest, and sha-full-commit tags after all tests, native Chromium launches, health checks, desktop builds, and approval.

docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:59188/health
docker compose logs --tail=200 app

The health response contains status, database, version, commit, and build_time. Update after backing up:

docker compose pull app
docker compose up -d
docker compose logs --tail=100 app

PostgreSQL backup:

set -a
. ./.env
set +a
docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
  > "xianyu-$(date +%Y%m%d-%H%M%S).sql"

Restore only after stopping app and validating the backup. docker compose down retains volumes; do not use down -v in production because it deletes database and application-data volumes. Use Caddy, Nginx, Traefik, or a cloud load balancer for HTTPS and add -secure to the application command.

Repository areas include cmd/server, cmd/browser-install, cmd/tray, cmd/init-admin, cmd/dbverify, and cmd/dbseed; internal/account, application, adapter, automation, browser, composition, db, engine, notify, renewal, server, and xianyu; frontend; docs; packaging; and scripts.

Local commands:

go run ./cmd/server -db data/xianyu_data.db -addr :59188
npm --prefix frontend ci
npm --prefix frontend run dev
make frontend
make build

The Vite development server is available at http://localhost:3000 and proxies API requests to http://localhost:59188.

Quality checks:

make fmt
make vet
make lint
make test
make smoke   # start the real binary and verify health, setup, login, core lists, the front page, and graceful exit
make cover
make check
npm --prefix frontend run typecheck
npm --prefix frontend test
npm --prefix frontend run build
./scripts/docker-full-test.sh

Use local fixtures, httptest, mock accounts, and local browser pages. Never use real credentials in tests.

Open the management page after starting the service. If no administrator exists, set and confirm a password of at least eight characters; the system creates admin and signs in. Docker Compose requires a non-empty XIANYU_ADMIN_PASSWORD. Headless or password-reset environments can use:

go run ./cmd/server -init-admin -db data/xianyu_data.db -admin-password 'new-password'

Confirm that POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, and DATABASE_URL match. The Compose hostname is postgres, not localhost. URL-encode password characters such as @, :, /, and #. Confirm PostgreSQL health with docker compose ps.

Prefer the project image or a standalone package, which contains the matching driver and Chromium runtime. Source runs need permission to download the driver and browser. Set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH for an external browser and PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 when appropriate. Containers need sufficient shared memory and a writable browser_data volume.

Check Account Management status and renewal logs, complete official verification in the Xianyu app, and check server time, timezone, and connectivity. Do not run one account in multiple instances. If verification loops, clear credentials, disable the account, complete verification in Xianyu’s official web version, wait, and try again.

This is expected security behavior. Restore the original key. If it cannot be recovered, log in again and re-enter protected keys. Do not clear a production database or bypass decryption checks.

• Expose the management console through HTTPS and restrict trusted sources.
• Use separate strong credentials for administrator, database, GHCR, AI, SMTP, and notification services.
• Keep XIANYU_DATA_KEY fixed and back it up offline with the database.
• Never commit .env, database files, Cookies, QR codes, logs, browser data, API keys, or Webhook tokens.
• Back up PostgreSQL and test restoration.
• Use version or SHA image tags in production.
• Stop an account and inspect audit and renewal logs when behavior is abnormal.
• Report vulnerabilities privately through SECURITY.md.

Read CONTRIBUTING.md before opening an Issue or Pull Request. Chinese is the primary community language, and English contributions are welcome. Follow the Code of Conduct.

Before submitting, separate unrelated topics into independent commits, add focused tests for protocol/database/key business behavior, run make check and frontend tests, and remove all real accounts, Cookies, orders, cards, keys, and other sensitive data.

Licensed under the Apache License 2.0, Copyright © 2026 Christ9038. Preserve NOTICE and the applicable license notices when distributing original or derivative works, and clearly mark modified files.

This project provides technical research and self-hosted management capabilities. It does not guarantee compatibility with future Xianyu changes, account risk-control decisions, business continuity, or data integrity. Users are solely responsible for legal compliance, platform compliance, account authorization, backups, account restrictions, transaction disputes, data loss, and all other consequences. Do not use it for spam, fraud, unauthorized access, bypassing platform restrictions, or illegal activity.

This project receives discussion and feedback from the LINUX DO community:

Visit the LINUX DO community