xianyu-auto-reply-fix: a self-hosted Xianyu (Goofish) customer service bot

What xianyu-auto-reply-fix actually automates on a Xianyu account

The problem is mundane and repetitive: a Xianyu seller gets the same questions about price, stock and shipping, and has to confirm delivery on orders by hand. This project puts a Python service in front of one or more Xianyu accounts and answers for you. The README lists keyword replies, default replies, per-item replies, image keyword replies and AI replies, plus automatic delivery confirmation through text, batch data, an API or images, with duplicate handling.

It is built for people running a small number of seller accounts who want the replies to stay on their own machine. The repository describes a multi-user system with registration, email verification, a graphical captcha, permission control and per-user data isolation, so one instance can serve several operators. The README states the project is a community-maintained unofficial tool with no affiliation to Xianyu or Alibaba, and that it is intended for learning and research rather than commercial use.

CookieManager, XianyuLive and the WebSocket message path

The architecture diagram in the README shows four layers. A FastAPI web interface sits on top. Below it, CookieManager holds per-account tasks and status. Below that, XianyuLive runs one instance per account, maintaining a WebSocket connection and handling messages. Two services hang off XianyuLive: AIReplyEngine for AI replies and conversation context, and FileLogCollector for real-time logs and statistics. SQLite stores users, item information and configuration.

The practical consequence is that message handling is bound to a live WebSocket per account, not to polling. That is why the dependency list carries both websockets and aiohttp with aiohttp-socks and python-socks for proxy support: the connection is the thing that has to survive. It also explains why Playwright and DrissionPage are in requirements.txt. Login, captcha and slider handling are browser work, and the Docker image installs Chromium dependencies and sets PLAYWRIGHT_BROWSERS_PATH to /ms-playwright. The compose file enables USE_XVFB, ENABLE_HEADFUL and ENABLE_VNC with DISPLAY=:99, so the browser runs headful inside a virtual display you can watch over VNC when a login or slider needs a human.

Installing xianyu-auto-reply-fix with Docker Compose

The README recommends Docker Compose. Before starting, create a .env in the repository root so the defaults are not used. The README gives this example, and says the default administrator password and JWT key in docker-compose.yml are for local trials only:

ADMIN_PASSWORD=replace-with-a-strong-password
JWT_SECRET_KEY=replace-with-a-long-random-string

Then clone and start the stack. The README notes that --build is only needed when you changed the Dockerfile or dependency files:

 git clone https://github.com/GuDong2003/xianyu-auto-reply-fix.git
 cd xianyu-auto-reply-fix
 docker compose up -d

After startup the README points to three addresses: the admin interface at http://localhost:9000, API documentation at http://localhost:9000/docs, and a health check at http://localhost:9000/health. The first initialization account is admin / admin123, which the README says to change immediately after the first login. Persistent state lives in data/, logs/ and backups/, and the README asks you to back those up before an upgrade or a container rebuild.

Running it locally, and the ports that differ from Docker

Local execution is documented separately and uses a different default port, 8090 instead of the 9000 mapping Docker Compose exposes. The README gives this sequence, including the Chromium install that Playwright needs:

 python -m venv venv
 source venv/bin/activate
 pip install --upgrade pip
 pip install -r requirements.txt
 playwright install chromium
 python Start.py

On Windows the README says to activate with venv\Scripts\activate. If the browser binaries are missing later, the FAQ repeats the fix as playwright install chromium inside the activated environment. Port conflicts are handled either in docker-compose.yml (or docker-compose-cn.yml) for Docker, or through API_PORT or global_config.yml for a local run. The AI reply configuration follows a single model_name / api_key / base_url / api_type pattern, and the README lists OpenAI-compatible, OpenAI Responses, DashScope, Gemini, Anthropic and Azure OpenAI endpoints as supported, with third-party OpenAI-compatible services reachable through a custom base_url.

The security boundary you have to draw yourself

The README's pre-deployment section is unusually direct, and it is worth taking literally. It says not to expose ports 5900 (VNC) and 6080 (noVNC) to the public internet, because those give remote control of the browser session that holds your Xianyu login. It asks for an HTTPS reverse proxy in front of the admin interface and a restriction on who can reach it. It warns that data/, logs/, backups/ and global_config.yml can contain runtime data or sensitive configuration and should not be committed or attached to issues. Cookies, tokens, account passwords and database credentials are named as sensitive, and public logs or screenshots should be redacted first.

This is the honest shape of the trade-off. The compose file mounts the whole repository into /app for development convenience and runs the container as user "0:0" to avoid permission problems. Both choices are convenient and both widen what a compromise reaches. The project ships the material to secure it; it does not secure it for you.

Where xianyu-auto-reply-fix is the wrong tool

The AGPL-3.0 licence is the first constraint, and the README states it plainly: if you modify the code and offer it to users over a network, the licence's source-availability and notice-retention obligations apply. A closed SaaS wrapper around this codebase is not what the licence contemplates, and the README also labels the project as study and research use rather than commercial use. That is a positioning statement, not a legal opinion, and it is worth reading the licence text itself.

The second constraint is operational. This is browser automation against a platform that actively defends against it, which is why slider handling, captcha and manual cookie login all appear in the repository as separate debug scripts. The README credits contributors for slider handling ideas, which tells you the mechanism needs maintenance as the platform changes. If you want a reply system that does not depend on a headful Chromium session, or you cannot tolerate an account needing manual intervention when a challenge appears, this is the wrong tool. The dependency list is also heavy: pandas, openpyxl, xlsxwriter, Pillow, qrcode, cryptography and passlib are all in requirements.txt, and the Dockerfile installs a long list of Playwright system libraries. The image is not small.

How it differs from the projects it credits

The README's acknowledgements section is the clearest statement of lineage. It credits myfish for the scan-code login approach, XianYuApis for API technical reference, XianyuAutoAgent for automation handling ideas, and xianyu-auto-reply for the base framework and initial implementation. This repository is a fix and extension of that last one, which is also what the name says.

The difference in approach shows up in what was added around the core: a multi-user layer with registration, email verification and captcha; a web admin panel with order management, notification channels and online customer service; an AIReplyEngine with conversation context; and a documented release and hot-update process with release_precheck.py and generate_update_manifest.py. Where the upstream reference was a single-account automation script, this one is packaged as a small multi-tenant service. If you only need one account and a keyword table, the simpler ancestors in that list are closer to the job.

Maintenance cost, releases and what the repository does not document

The last push to main was on 2026-08-22, the same day as the v2.0.7 release, and v2.0.6 and v2.0.5 arrived on 2026-08-14 and 2026-07-10. The release cadence over that window is roughly one to two months, and the repository is not archived. That is the whole of what the metadata supports; there is no published support commitment.

Upgrade cost is partly documented and partly not. The README points to docs/release.md for the hot-update checklist, version numbering and the release flow, and there is an auto_updater.py in the tree. What the README does not document is rollback: it tells you to back up data/, logs/ and backups/ before upgrading or rebuilding, but it does not describe how to revert to a previous version if a migration goes wrong. The database layer is described as SQLite with automatic migration, so the state you would need to restore is the database file plus the configuration. Treat the backup step as the rollback plan, because nothing else in the repository is presented as one. The AGPL-3.0 licence governs redistribution and network use; for anything beyond personal study, read the licence and the SECURITY.md vulnerability reporting path rather than relying on the README summary.

Editorial conclusion

Adopt it if you run Xianyu seller accounts, are comfortable with Docker and Playwright, and accept the AGPL-3.0 terms; the project's own README positions it as study and research use. Do not adopt it if you need a hosted service, want no browser automation in your stack, or cannot keep the default admin password and JWT secret out of a public deployment. Before trusting it with a live account, verify three things yourself: that your .env overrides ADMIN_PASSWORD and JWT_SECRET_KEY, that the Playwright Chromium install succeeds in your environment, and that the ports 5900 and 6080 are not reachable from the public internet.

Frequently asked questions

Official sources

1. GuDong2003/xianyu-auto-reply-fix on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases