Skip to content
Projects

Evvvvvvvan/XianYuSmart has 108 GitHub stars and 25 forks. GitHot measured 0 stars in 24 hours, +7 in 7 days, and +9 in 15 days. Last checked 2026-11-17 02:45 UTC. Last push 2026-11-14.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
+7
in 15 days
+9
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

闲鱼全流程自动化运营系统:从商机挖掘、商品发布,到 AI 客服、固定内容/卡密自动发货、评价与售后跟进一站式完成;支持多账号、多租户、异常恢复和 Docker 自部署。

AI

README.en.md

Original

XianYuSmart

English | 简体中文

Stars Forks Release Star History Java 21 Spring Boot 3.5 Vue 3 MySQL License

Automate virtual product ordering, delivery, support, and reviews as much as possible. Routine orders run unattended while exceptions are handled in one place.

XianYuSmart is a virtual product operations system for Xianyu in multi-tenant environments. After a buyer places an order, the platform can automatically deliver fixed resources or card keys based on the product and reach the buyer through delivery credentials, private chat, or both channels. Common inquiries, receipt guidance, and review follow-ups before and after a transaction can also be handled automatically according to configured rules. Merchants only need to focus on cases that genuinely require attention, such as low inventory, disconnected accounts, delivery failures, and pending reviews.

The system does more than send a block of text after receiving an order. It connects order discovery, idempotent queuing, inventory reservation, dual-channel delivery, failure retries, and manual review into a complete recoverable workflow. Fixed content and card-key delivery modes are strictly mutually exclusive, while accounts, products, messages, orders, inventory, tasks, and AI knowledge bases are isolated by tenant. Core task workflows rely only on MySQL, without requiring Redis or a message queue, balancing deployment cost with future extensibility.

Current version: 2.0.9 · View changelog

Community & Support · Benefits for Merchants · Technical Highlights · Problems Solved · Feature Scope · Feature Entry Points & Setup Order · Business Workflow · Technical Baseline · Container Image Deployment · Quick Start · Configuration · Development Build · Build & Verification · Directory Responsibilities · Routine Operations · Usage Boundaries · License & Disclaimer · Star History

Community & Support

Issues, experience, and suggestions from real-world use help make XianYuSmart more stable and easier to use. Join the WeChat group to discuss deployment configuration, connection troubleshooting, automated delivery, and operational practices. If the project saves time or solves a practical business problem, voluntary donations are also welcome to support ongoing maintenance.

Join the WeChat Group

Discuss configuration, troubleshooting, and practical experience with maintainers and users, and stay informed about project progress. Feature requests, shared practices, and project contributions are all welcome.

XianYuSmart WeChat group QR code

Group QR codes expire periodically. Use the WeChat contact option to request a fresh invitation.

Alternative: Add on WeChat

If the group QR code has expired or does not work, scan the code below to add the contact on WeChat. Mention "XianYuSmart group" in the friend request to receive the latest group invitation.

WeChat contact QR code, NullPointerException

WeChat nickname: NullPointerException

Support the Project

Every contribution supports documentation improvements, compatibility verification, issue fixes, and continued maintenance. Any amount is an encouragement to keep the project moving forward.

XianYuSmart donation QR code

Donations are entirely voluntary and do not include commercial services, feature priority, or any commitment

Benefits for Merchants

Scenario What XianYuSmart Automates Direct Benefit
Selling cloud-drive links, tutorials, or other fixed resources Reuses fixed-content templates and automatically substitutes member names, order numbers, and delivery content No repeated copy-and-paste for every order
Selling activation codes, redemption codes, or membership cards Reserves card keys according to order quantity, then consumes them and records their destination after successful delivery Reduces duplicate keys, missing keys, and inventory discrepancies
Card keys supplied by an existing procurement system Calls an HTTPS API for each order, uses an idempotency key to prevent duplicate purchases, and sends uncertain results for manual verification No need to preload all inventory, and timeouts do not cause blind duplicate charges
Buyers need to receive content promptly Delivery credentials and private chat can be enabled independently or used together Delivery content is easier to find, reducing repeated inquiries
Repetitive inquiries consume too much time Replies using keywords, product-specific rules, or an AI knowledge base, with support for manual takeover Common questions are handled automatically while complex conversations remain available for manual handling
Follow-up is required after buyers confirm receipt Sends custom receipt messages in order and performs reviews according to configuration After-sales guidance follows a consistent process without relying on memory
Many products require centralized maintenance Reuses fixed templates, card-key warehouses, review message pools, and batch rules Less duplicate configuration; one change can apply to multiple products
Service restarts, network instability, or API failures occur Recovers persistent tasks automatically, retries with backoff, and sends uncertain outcomes for manual review Exceptions are neither silently lost nor blindly resent
Multiple merchants share the same platform Isolates business data and AI knowledge bases by tenant Each merchant manages only their own accounts, products, orders, and configuration
Returning buyers must be identified or risky buyers must be excluded from automation Automatically accumulates buyer interactions and transaction data, with labels, notes, and automation pause states Customer relationships are clearer, and exceptional buyers no longer trigger automated replies or delivery
Critical exceptions require timely notification Sends Webhook notifications for disconnected accounts, expired credentials, delivery exceptions, and low inventory while retaining delivery logs No need to watch the dashboard continuously to notice cases requiring intervention

For buyers, the core experience is faster content delivery after ordering, clearer delivery entry points, and faster answers to common questions. For merchants, the main shift is from processing every order manually to configuring rules, handling exceptions, and reviewing results.

Technical Highlights

Engineering Design Implementation Value
Atomic card-key delivery Uses MySQL row-level locks to reserve a complete order, consumes inventory after successful delivery, and releases or sends it for manual review after failure Prevents duplicate keys, missing keys, and overselling under concurrent orders
Recoverable task queues Persists order and reply tasks with worker leases, timeout recovery, and backoff retries Processing continues after a process exit or server restart
Idempotent dual entry points Queues WebSocket real-time events and order API compensation uniformly by order number Balances real-time processing and completeness without delivering the same order twice
Multi-tenant data boundaries Enforces tenant isolation through TenantContext, tenant fields, composite unique indexes, and database migrations Prevents accounts, orders, inventory, configuration, and knowledge bases from leaking across tenants
Real-time message pipeline Uses Java-WebSocket access, MessagePack decoding, message persistence, and asynchronous business processing Long-running business work does not block persistent connection reception
Isolated AI customer service Uses Spring AI, tenant-specific dynamic clients, and separate vector stores, supporting keywords, product rules, and manual takeover AI can be configured per tenant while deterministic rules remain available at any time
Lightweight runtime boundaries Uses bounded thread pools, finite task queues, batch claiming, and database connection pool limits Controls resource usage without requiring heavyweight middleware
Strategy-based extensibility Parses fixed-content/card-key delivery strategies and keyword/AI reply strategies independently New delivery or reply modes can be added without rewriting the main workflow
Idempotent external procurement Uses order-level request tokens, response quantity validation, and uncertain-result isolation Prevents duplicate purchasing and incorrect delivery when integrating external card-key systems
Proactive notifications and diagnostics Supports multi-channel notifications, signature validation, SSRF protection, and a unified exception view with processing states Critical events arrive promptly, while resolved historical exceptions stop causing distraction

This implementation is suitable for studying reliable task scheduling, event-driven automation, multi-tenant data isolation, virtual inventory consistency, and AI customer service orchestration. The repository provides a complete loop from the frontend workspace and backend state machine to database migrations and container deployment, rather than code that only supports a single happy path.

If these engineering challenges are also important, Star the repository to follow its progress. For custom delivery or reply workflows, Fork the project and extend the existing strategy interfaces.

Problems Solved

Operational Problem Solution
Duplicate, missing, or oversold card keys MySQL row-level locks, complete-order reservation, consumption after successful delivery, and release or manual review after failure
Lost order or reply tasks after a service restart Persistent delivery and reply tasks that recover automatically after lease expiration
Duplicate delivery triggered by multiple entry points Idempotent queuing by order number, with WebSocket and API discovery entering the same task queue
Uncontrolled resource usage during message spikes Shared bounded thread pools, finite queues, batch claiming, and connection pool limits
Incorrect automated customer service replies Persistent manual takeover state, with keyword, product, and AI replies evaluated using a unified result model
Inventory and failure conditions discovered too late A dashboard that centralizes available card keys, low inventory, pending cases, review-required cases, and failed tasks
Business data shared accidentally between merchants Tenant isolation for accounts, products, messages, orders, card keys, settings, tasks, and AI knowledge bases
Disconnected product publishing and distribution workflows Unified orchestration for source collection, product selection, materials, batch publishing, deletion, and compensation tasks
Reviews and product refreshes depend on manual inspection Product management centralizes review switches, trigger modes, message pools, batch application, and daily deduplicated refreshes; the order page handles manual and mutual reviews
Unclear public network access boundaries The application binds only to a local port while Nginx provides HTTPS, rate limiting, and reverse proxying
Buyer information scattered across messages and orders Buyer profiles are created automatically and aggregate interactions, orders, transaction totals, labels, and operational notes
External procurement timeouts leave payment status uncertain Retries use a fixed idempotency key, while uncertain network outcomes lock the order for manual verification

Feature Scope

Operations Automation Reliable Delivery Multi-Tenant Operations
Accounts, cookies, connections, and disconnect alerts Atomic multi-quantity card-key reservation and idempotent delivery Automatic MySQL schema creation and version migrations
Products, SKUs, delivery rules, and card-key warehouses Delivery task retries, lease recovery, and manual review Docker Compose, health checks, and HTTPS proxying
Strictly exclusive fixed-content/card-key modes, with independently enabled credential and chat channels Manual takeover and delayed reply recovery Business data backups and operation logs
Keyword, product-level, and AI automated replies Full traceability for messages, orders, and delivery results Sensitive values such as cookies, API keys, and email passwords excluded by default
Revenue, delivery, replies, inventory, and exception workspace Failed tasks collected in a centralized queue Bounded thread pools, connection pools, and batch scheduling parameters
Materials, addresses, sources, product selection, and publishing rules Automatic/manual reviews, custom messages, automatic product refreshes, and order status tracking Tenant-specific AI clients, configuration, and vector stores
Commission accounts, distribution settlement, and compensation tasks Published ID write-back, short-link repair, and coupon binding Announcements, feedback, risk events, and operation logs
Buyer labels, notes, and risk automation pauses Local inventory and external API card-key supply Webhook notifications, delivery logs, and system diagnostics

Feature Entry Points & Setup Order

Each automation capability maintains its switches and templates in one business module. Other pages only display status, execution results, or links to the configuration entry point, preventing settings in multiple places from overriding each other.

Single Configuration Entry Point Responsibilities
Connection Management Cookie updates, connection status, WebSocket reconnection, and account health checks
Product Management Product synchronization and editing, automatic review rules, review message pools, batch application, and automatic product refreshes
Fixed Content Templates Reusable fixed delivery content and variable templates for download links, instructions, and similar resources
Card-Key Warehouses Local card-key inventory, external procurement APIs, batch imports, inventory alerts, and usage records
Automated Delivery Selects fixed-content or card-key mode for a product and configures the master switch, credential delivery, and private-chat delivery
Automated Replies Keywords, product-specific replies, AI replies, and manual takeover settings
Buyer Management Views buyer interactions, orders, and transaction data, and maintains labels, notes, and automation pause states
Orders & Reviews Views fulfillment status, manual reviews, mutual reviews, and failed retries without maintaining automatic review rules
Notifications & Diagnostics Checks account, delivery, reply, and inventory exceptions; marks one or many as processed; configures notification channels and views delivery logs
Operation Logs & System Settings Queries business operations, exception causes, and tenant-specific system parameters

Recommended setup order:

  1. Add a Xianyu account in Connection Management and confirm that the Cookie is valid and WebSocket is connected.
  2. Synchronize products. Create a fixed-content template for fixed resources, or create a card-key warehouse and import inventory for card-key products.
  3. Choose exactly one delivery mode for each product in Automated Delivery, then enable credential and private-chat channels as needed.
  4. Configure keyword, product-specific, or AI reply strategies in Automated Replies.
  5. Configure automatic review modes and messages centrally in Product Management, and enable automatic product refreshes as needed.
  6. Review execution results and exception tasks under Orders & Reviews, Operation Logs, and the dashboard queue.

Business Workflow

flowchart LR
    XY["Xianyu messages and orders"] --> WS["Connection and message routing"]
    WS --> SAVE["Message persistence"]
    WS --> REPLY["Reply task"]
    WS --> DISCOVER["Order discovery"]
    API["Order API compensation"] --> DISCOVER
    DISCOVER --> TASK["Persistent delivery task"]
    TASK --> CLAIM["Lease claiming with bounded concurrency"]
    CLAIM --> RULE["Product and SKU rule resolution"]
    RULE -->|Card-key mode| CARD["Complete-order card-key reservation"]
    RULE -->|Fixed-content mode| FIXED["Fixed-content template"]
    CARD --> CHANNEL["Credential / private-chat channels"]
    FIXED --> CHANNEL
    CHANNEL --> SEND["Xianyu message delivery"]
    SEND -->|Success| COMMIT["Consume inventory and record delivery"]
    SEND -->|Retryable failure| RETRY["Backoff retry"]
    SEND -->|Uncertain outcome| REVIEW["Manual review"]
    RETRY --> TASK
    REPLY --> HUMAN["Manual takeover check"]
    HUMAN --> RULES["Keyword / product / AI"]
    RULES --> SEND
    COMMIT --> DASH["Merchant workspace"]
    REVIEW --> DASH

Product Operations Loop

Source collection -> selection rules -> material library -> single or batch publishing -> product ID write-back -> automatic refresh/reviews -> distribution settlement

  • Publishing and deletion rules generate persistent tasks on a per-tenant schedule and retry failures with backoff.
  • Compensation tasks uniformly handle published product ID write-back, in-app short-link repair, and coupon warehouse binding.
  • Announcements, feedback, risk events, and task results enter the operations center for tenant-specific tracing.
  • The dashboard provides quick-start guidance and direct links to core features. The operations center provides usage guides, module descriptions, required-field validation, and next-step prompts. Automatic review rules are maintained centrally in Product Management, while the order page only handles manual reviews and mutual review results.

Delivery States

PENDING -> PROCESSING -> SUCCESS

  • Temporary network or API failure: PROCESSING -> RETRY -> PENDING
  • Retry limit exceeded or uncertain delivery result: PROCESSING -> REVIEW_REQUIRED
  • Unexpected process exit: claim again after the lease expires

Card-Key States

AVAILABLE -> RESERVED -> USED

  • Inventory is reserved only when the complete order quantity is available.
  • Inventory becomes USED only after message delivery is confirmed.
  • Confirmed delivery failures release inventory back to AVAILABLE.
  • Uncertain delivery outcomes preserve the association and enter manual review to prevent duplicate delivery.

Technical Baseline

  • Java 21
  • Spring Boot 3.5
  • MySQL 5.7+
  • Flyway
  • MyBatis-Plus
  • Vue 3, TypeScript, Vite
  • Docker Compose
  • Nginx

Container Image Deployment

Every official Release automatically publishes a linux/amd64 image to GitHub Container Registry. Fixed versions are suitable for production deployment, while latest is intended for trying the latest official release.

docker pull ghcr.io/evvvvvvvan/xianyusmart:v2.0.9
docker pull ghcr.io/evvvvvvvan/xianyusmart:latest

Start a fixed version using the repository's Docker Compose configuration:

Linux:

cp .env.example .env
# Update the database password and strong JWT secret in .env
export APP_IMAGE=ghcr.io/evvvvvvvan/xianyusmart:v2.0.9
docker compose pull app
docker compose up -d --no-build

Windows PowerShell:

Copy-Item .env.example .env
notepad .env
$env:APP_IMAGE = 'ghcr.io/evvvvvvvan/xianyusmart:v2.0.9'
docker compose pull app
docker compose up -d --no-build

The image still depends on the MySQL, JWT, and cross-origin settings in .env. Windows Docker Desktop must use Linux container mode. Pin a version tag in production to avoid unplanned changes from updates to latest.

Quick Start

Requirements

  • Docker Engine 24+ or Docker Desktop
  • Docker Compose v2
  • At least 2 CPU cores and 2 GB of memory recommended for Linux production environments
  • Windows can use Docker Desktop for functional testing

Linux

chmod +x install.sh
./install.sh

Windows PowerShell

Copy-Item .env.example .env
notepad .env
docker compose up -d --build
docker compose ps

All three example secrets in .env must be changed before startup. JWT_SECRET must contain at least 32 random bytes, and database passwords must not be reused.

Open http://localhost:12400 after startup.

A fresh database opens the tenant account creation page on first access. When tenants already exist, a new tenant can still be registered from the login page. Password length is limited to 8–72 characters.

Public HTTPS

  1. Save the certificates as:
deploy/nginx/certs/fullchain.pem
deploy/nginx/certs/privkey.pem
  1. Update .env:
ALLOWED_ORIGINS=https://shop.example.com
TRUST_PROXY=true
  1. Start the proxy profile:
docker compose --profile proxy up -d --build
  1. After pointing the domain to the server, open https://shop.example.com.

The application container exposes port 12400 only on 127.0.0.1, and all public traffic passes through Nginx. MySQL and port 12400 must not be exposed directly in production.

Configuration

Copy .env.example to .env, then update it for the environment:

Variable Description Recommended Value
DB_NAME MySQL database name xianyusmart
DB_USERNAME Application database account Dedicated least-privilege account
DB_PASSWORD Application database password Random strong password
DB_ROOT_PASSWORD MySQL root password Different from the application password
JWT_SECRET Login token signing secret At least 48 random bytes
BOOTSTRAP_ADMIN_USERNAME Admin account created on a brand-new environment admin
BOOTSTRAP_ADMIN_PASSWORD Admin password for the first startup 12 random bytes; only applied when no admin exists
ADMIN_RESET_USERNAME Admin account whose password should be reset Fill in only while resetting
ADMIN_RESET_PASSWORD New admin password At least 8 characters with two of letters/digits/symbols; remove the variables after a successful login
ALLOWED_ORIGINS Frontend origins allowed to access the application Complete HTTPS domain
TRUST_PROXY Whether proxy headers are trusted Set to true only behind Nginx
UPDATE_RELEASE_API GitHub Releases API Uses this project's latest Release by default; leave empty to disable update checks
DB_POOL_MAX_SIZE Maximum database connections Default 10 for a single instance
DB_POOL_MIN_IDLE Minimum idle connections Default 2
JAVA_OPTS JVM container memory policy Default value is suitable for small instances

The following tuning variables can be added under app.environment in compose.yaml:

Variable Default Purpose
EXECUTOR_CORE_SIZE 4 General business worker threads
EXECUTOR_MAX_SIZE 8 Maximum general business worker threads
EXECUTOR_QUEUE_CAPACITY 500 Bounded task queue capacity
DELIVERY_CLAIM_BATCH_SIZE 20 Delivery tasks claimed per cycle
DELIVERY_DISPATCH_DELAY_MS 1000 Delivery scheduling interval
DELIVERY_LEASE_SECONDS 120 Task processing lease
DELIVERY_MAX_ATTEMPTS 3 Maximum delivery attempts
PRINT_RAW_MESSAGE false Raw message logging; keep disabled in production

Before increasing concurrency, evaluate Xianyu API rate limits, active tenant count, MySQL connections, and server memory together. Keep the defaults first and use the exception queue to identify real bottlenecks before tuning.

Development Build

Local Development on Windows

Prepare Java 21, Node.js 20+, and MySQL 5.7+, then create the database and account:

CREATE DATABASE xianyusmart CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'xianyusmart'@'localhost' IDENTIFIED BY 'replace-with-strong-password';
GRANT ALL PRIVILEGES ON xianyusmart.* TO 'xianyusmart'@'localhost';
FLUSH PRIVILEGES;

Backend:

$env:DB_PASSWORD = 'replace-with-strong-password'
$env:JWT_SECRET = 'replace-with-at-least-32-random-bytes'
.\mvnw.cmd spring-boot:run

Frontend:

Set-Location vue-code
npm ci
npm run dev

The frontend development server runs at http://localhost:5173 and proxies API requests to http://localhost:12400.

Build & Verification

Set-Location vue-code
npm ci
npm run type-check
npm run build:spring
Set-Location ..
.\mvnw.cmd clean test
.\mvnw.cmd clean package

On Linux, replace mvnw.cmd with ./mvnw.

Directory Responsibilities

src/main/java/com/xianyusmart/
├─ controller/          HTTP APIs and workspace aggregation
├─ service/             Account, message, reply, delivery, operations orchestration, and persistent tasks
├─ service/delivery/    Text and card-key delivery strategies
├─ websocket/           Xianyu persistent connections, routing, and reconnection
├─ mapper/              MySQL data access and task locking
├─ interceptor/         Authentication boundaries
├─ backup/              Optional data backups
└─ config/              Thread pools, web, database, and AI configuration

src/main/resources/
├─ db/migration/        Flyway database schema
├─ static/              Built Vue frontend
└─ application.yaml     Runtime parameters

vue-code/src/
├─ api/                 Frontend API wrappers
├─ components/          Shared components and layouts
├─ views/               Merchant business pages
├─ utils/               Request, notification, and confirmation utilities
└─ assets/              Minimal commercial theme

deploy/nginx/            HTTPS, rate limiting, and reverse proxy
compose.yaml             Application, MySQL, and Nginx orchestration

Routine Operations

View status and logs:

docker compose ps
docker compose logs -f --tail=200 app
docker compose logs -f --tail=200 mysql

After updating local code:

docker compose up -d --build

Admin cannot sign in

  1. Check the 管理员账号自检 (admin credential self-check) line in the startup logs. It reports whether the username contains leading/trailing whitespace, whether password is a valid BCrypt hash, and whether the role and status are correct:

    docker compose logs --since=10m app | grep "管理员账号自检"
    
  2. If signing in still fails, add these two lines to .env temporarily, then restart the app:

    ADMIN_RESET_USERNAME=admin
    ADMIN_RESET_PASSWORD=your-new-password
    docker compose up -d app
    
  3. The reset rewrites the BCrypt hash, restores the ADMIN role and the enabled status, and clears every login token of that account. Remove both variables and restart again after signing in successfully so the plaintext password no longer sits in the environment.

Captcha says the Cookie expired

When the automated mode detects that the platform redirected the challenge URL to the sign-in page, it reports the Cookie as expired instead of waiting for a slider that will never appear. Switch to "人工拖动" (manual drag), scan the QR code shown in the server browser frame with your phone, and the app collects the refreshed Cookie and reconnects automatically once the sign-in completes.

Back up MySQL:

docker compose exec mysql mysqldump -uxianyusmart -p xianyusmart > xianyusmart.sql

Stop application writes and verify the backup file before restoring. Business data exports do not include sensitive configuration such as cookies, AI keys, or email passwords. Runtime environment variables and certificates must be preserved separately for disaster recovery.

Usage Boundaries

  • Xianyu APIs, cookies, and risk-control policies may change, so account status and exception queues require ongoing attention.
  • Automation frequency must comply with platform rules and must not be used for fraud, harassment, or bypassing platform security mechanisms.
  • Public deployments must enable HTTPS, strong passwords, a host firewall, and regular backups.
  • Fresh environments use MySQL; automatic migration from historical SQLite data is not provided.

License & Disclaimer

This project uses the PolyForm Noncommercial License 1.0.0 and is licensed only for personal learning, technical research, experiments, and other noncommercial purposes.

All commercial use is prohibited, including sales, paid deployment, hosting services, SaaS, managed operations, commercial lead generation, paid training, and direct or indirect profit through advertising, subscriptions, commissions, or value-added services.

  • Usage must comply with applicable laws and regulations, Xianyu's platform terms of service, and account usage rules.

Downloading, copying, modifying, deploying, running, or distributing this project indicates acceptance of the complete usage restrictions and disclaimer.

⭐ Star History

XianYuSmart Star History Chart Generated by scripts/gen_star_history.py and updated daily by GitHub Actions · Click the image to view it at full size