Ydisks Xianyu Helper 是一个闲鱼多账号管理、自动发货和消息回复系统。它完全自托管，支持通过 Docker 快速部署，也可以从源码运行或安装桌面版。下面这份教程会帮你一步步完成部署。

📋 准备工作

在开始之前，你需要先准备好以下环境：

  • Docker 部署（推荐）：需要安装 Docker Engine 或 Docker Desktop，并确保 Docker Compose 版本为 v2。
  • 源码运行：需要 Go 1.26.4 或兼容版本、Node.js 24 和 npm、Chromium 系统依赖（可选 SQLite）。
  • 桌面安装包：直接从 Releases 页面下载对应系统的安装包即可。

重要提醒：根据项目说明，此工具仅供个人学习研究，未获得闲鱼官方授权。使用时请务必遵守平台规则和法律法规，并自行承担相关风险。

🐳 方案一：使用 Docker Compose 部署（推荐）

这是最快捷、最稳定的方式，支持 Linux x86_64、Linux ARM64 和 Apple Silicon。

1. 克隆项目并配置环境变量

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

2. 编辑 .env 文件
你至少需要设置以下变量，请务必修改为强密码和随机密钥：

1
2
3
4
5
6
POSTGRES_DB=xianyu
POSTGRES_USER=xianyu
POSTGRES_PASSWORD=替换为强密码
DATABASE_URL=postgres://xianyu:url编码后的密码@postgres:5432/xianyu?sslmode=disable
XIANYU_DATA_KEY=替换为长期随机密钥
XIANYU_ADMIN_PASSWORD=替换为管理员密码

你可以用以下命令生成随机值：

1
2
openssl rand -hex 24
openssl rand -base64 48

注意：如果密码包含 @、:、/、# 等特殊字符，在 DATABASE_URL 中需要进行 URL 编码。

3. 启动应用

1
docker compose up -d

4. 访问控制台
在浏览器中打开 http://localhost:59188，使用你在 .env 中配置的管理员密码登录。

5. 升级与备份
升级前请务必备份数据库和 .env 文件。更新时执行：

1
2
docker compose pull app
docker compose up -d

PostgreSQL 备份命令：

1
2
3
4
5
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"

警告：不要在生产环境使用 docker compose down -v，因为这会删除数据库和应用程序数据卷。

🛠️ 方案二：从源码运行（适合开发调试）

1. 克隆仓库并安装依赖

1
2
3
4
git clone https://github.com/Christ9038/Ydisks-Xianyu-Helper.git
cd Ydisks-Xianyu-Helper
npm --prefix frontend ci
npm --prefix frontend run build

2. 启动服务

1
go run ./cmd/server -db data/xianyu_data.db -addr 127.0.0.1:59188

首次访问时，如果数据库中没有管理员，页面会显示初始化表单，让你设置管理员密码。
对于无头环境或需要重置密码的情况，可以使用以下命令：

1
go run ./cmd/server -init-admin -db data/xianyu_data.db -admin-password '替换为强密码'

提示：前端资源在构建时通过 go:embed 嵌入，重新构建前端后需要重启 Go 服务。

💻 方案三：桌面安装包

如果你不想管理服务器，可以直接从 Releases 页面下载对应系统的安装包。安装包内含后端服务 xianyu-server 和 Chromium，以及用于控制的托盘程序。

平台 服务 控制器 数据和日志位置
Windows Windows 服务 xianyu-tray.exe C:\ProgramData\YdisksXianyuHelper
macOS LaunchAgent 菜单栏程序 ~/Library/Application Support/YdisksXianyuHelper 和 ~/Library/Logs/YdisksXianyuHelper
Linux systemd 服务 无桌面托盘 /var/lib/ydisks-xianyu-helper 和 /var/log/ydisks-xianyu-helper

桌面版首次运行地址为 http://127.0.0.1:59188，在网页中设置并确认管理员密码即可。

⚙️ 关键配置说明

数据库连接优先级：DATABASE_URL > -db-url > -db

重要环境变量：

变量 默认值 说明
DATABASE_URL 空 SQLite、MySQL 或 PostgreSQL 连接 URL
XIANYU_DATA_KEY 空 用于加密 Cookies、密码、令牌等敏感信息的长期密钥
XIANYU_ADMIN_PASSWORD 空 Docker Compose 非交互式管理员初始化密码
XIANYU_UPLOAD_DIR data/uploads 批量上架的上传和临时资源目录
LOG_LEVEL info 日志级别：debug、info、warn、error
BROWSER_HEADLESS 每账号配置；Docker 中为 true 强制启用或禁用无头 Chromium

更完整的配置项和命令行选项，可以参考项目的 Deployment and Database Wiki。

🚀 首次使用流程

  1. 以管理员身份登录。
  2. 在 账号管理 中，使用闲鱼 App 扫描二维码登录。
  3. 仅通过官方流程完成人脸或安全验证。
  4. 等待账号上线后，同步商品和订单。
  5. 在 卡券库存 中创建发货内容。
  6. 在 自动化 中关联商品、卡券、规格和触发器。
  7. 使用 聊天 功能查看历史记录，并测试文本、表情或图片消息。
  8. 在 账号管理 中配置自动评价和每日刷新。
  9. 根据需要配置关键词回复、默认回复、AI 回复和通知。

注意：Go 客户端目前仅支持二维码登录。请勿分享 Cookies、密码、二维码或验证链接。

🔧 故障排查

  • 管理员初始化失败：打开管理页面，如果没有管理员，设置一个至少8位字符的密码。Docker Compose 要求 XIANYU_ADMIN_PASSWORD 非空。
  • PostgreSQL 连接问题：确认 POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD 和 DATABASE_URL 匹配。Compose 中的主机名是 postgres，不是 localhost。密码中的特殊字符需要 URL 编码。
  • Chromium 或 Playwright 问题：优先使用项目镜像或独立安装包，它们包含匹配的驱动和 Chromium 运行时。源码运行需要权限下载驱动和浏览器。
  • 账号离线或安全验证：检查账号管理状态和续期日志，在闲鱼 App 中完成官方验证，并检查服务器时间、时区和网络。不要在同一实例中运行同一账号的多个副本。
  • 丢失 XIANYU_DATA_KEY：这是预期的安全行为。请恢复原始密钥。如果无法恢复，需要重新登录并重新输入受保护的密钥。不要清空生产数据库或绕过解密检查。

🔒 安全建议

  • 通过 HTTPS 暴露管理控制台，并限制可信来源。
  • 为管理员、数据库、GHCR、AI、SMTP 和通知服务使用独立的强凭据。
  • 保持 XIANYU_DATA_KEY 不变，并与数据库一起离线备份。
  • 切勿提交 .env、数据库文件、Cookies、二维码、日志、浏览器数据、API 密钥或 Webhook 令牌。
  • 定期备份 PostgreSQL 并测试恢复流程。
  • 在生产环境使用版本或 SHA 镜像标签。
  • 当账号行为异常时，停止该账号并检查审计和续期日志。