Ydisks闲鱼助手”的官方仓库，这是一个基于 Go 和 React 构建的闲鱼多账号自动发货与消息回复系统。以下是完整的部署与使用教程。

⚠️ 重要法律与合规声明

在开始之前，请务必阅读并理解以下关键声明：

  • 非官方授权：本项目未获得闲鱼/阿里巴巴任何官方授权，调用的是闲鱼网页端非公开接口。
  • 违反用户协议：使用本软件将违反闲鱼用户协议，可能造成闲鱼账号封禁。
  • 风险自担：本项目仅用于个人技术学习研究，所有使用后果由使用者自行承担，项目作者不承担任何责任。
  • 随时可能归档：收到平台下架通知时，本项目会随时删除归档。

🧭 核心功能与适用场景

Ydisks闲鱼助手是一个自托管的 Web 管理系统，主要解决多账号管理、自动化和统一客服问题。

  • 多账号统一管理：集中管理多个闲鱼账号的在线状态、消息和订单。
  • 自动发货：针对数字商品（如兑换码、资料链接），付款后自动发送卡密或内容。
  • 智能客服：支持关键词自动回复、默认回复，并可接入 OpenAI 兼容的 AI 接口进行智能对话。
  • 自动化运营：支持自动评价、每日“擦亮”商品、订单同步等功能。
  • 数据看板：提供订单、营收、库存、商品销量等统计。

📦 部署方式

项目提供三种主要的部署方式，你可以根据技术背景和需求选择：

方式一：Docker Compose 部署（强烈推荐）

这是最便捷、最推荐的生产环境部署方式，适用于 Linux (x86_64/ARM64) 和 Apple Silicon。

步骤：

  1. 克隆仓库并进入目录：

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

  2. 配置环境变量：

    1
    cp .env.example .env

    编辑 .env 文件，至少修改以下配置（请使用强密码和密钥）：

    1
    2
    3
    4
    5
    6
    7
    8
    # 数据库密码（建议用 openssl rand -hex 24 生成）
    POSTGRES_PASSWORD=替换为高强度密码
    # 数据库连接串（注意替换密码并URL编码）
    DATABASE_URL=postgres://xianyu:替换为URL编码后的数据库密码@postgres:5432/xianyu?sslmode=disable
    # 数据加密主密钥（建议用 openssl rand -base64 48 生成，务必备份！）
    XIANYU_DATA_KEY=替换为长期固定的随机密钥
    # 管理员密码（Docker部署首次启动时使用）
    XIANYU_ADMIN_PASSWORD=替换为管理员密码

  3. 启动服务：

    1
    docker compose up -d

  4. 访问管理后台：浏览器打开 http://localhost:59188，使用用户名 admin 和 .env 中设置的 XIANYU_ADMIN_PASSWORD 登录。

更新镜像：docker compose pull app && docker compose up -d

方式二：从源码运行

适合开发或想自行编译的用户。

环境要求：Go 1.26.4+, Node.js 24+, Chromium 依赖。

步骤：

  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
    2
    # 如果不想通过网页初始化，可用此命令创建管理员
    go run ./cmd/server -init-admin -db data/xianyu_data.db -admin-password '你的密码'

  3. 启动后端服务：

    1
    2
    3
    4
    5
    # 使用 SQLite (默认)
    go run ./cmd/server -db data/xianyu_data.db -addr :59188

    # 禁用浏览器功能（无法登录账号）
    # go run ./cmd/server -db data/xianyu_data.db -addr :59188 -no-browser

  4. 访问：http://localhost:59188。如果数据库未初始化，页面会引导你设置管理员密码。

方式三：桌面端安装包

项目为 Windows、macOS 和 Linux 提供了独立的桌面安装包，适合希望获得原生应用体验的用户。

  • Windows：安装器会注册后台服务（YdisksXianyuHelper）并添加系统托盘，方便控制服务启停。
  • macOS：安装器会注册 LaunchAgent 后台服务和菜单栏控制器。
  • Linux：下载 tar 包，以 root 执行 ./install.sh 安装 systemd 服务。

桌面端安装后的固定位置如下：

平台 后台服务 数据与日志目录
Windows YdisksXianyuHelper Windows Service C:\ProgramData\YdisksXianyuHelper\data
macOS com.ydisks.xianyu-helper.server LaunchAgent ~/Library/Application Support/YdisksXianyuHelper
Linux ydisks-xianyu-helper.service systemd unit /var/lib/ydisks-xianyu-helper

🚀 初次使用流程

部署成功后，按照以下流程配置和使用：

  1. 登录账号：
    • 进入“账号管理”。
    • 使用闲鱼 App 扫描二维码完成账号授权。
    • 关键提示：每次重启程序都会向闲鱼申请登录凭证，频繁操作会触发风控！有账号登录时，不要频繁重启本程序。
  2. 准备交付内容：
    • 进入“卡密库存”，创建文本、批量卡密或图片类型的交付内容。
  3. 配置自动化规则：
    • 在“自动化规则”中，将闲鱼商品与你创建的卡密库存关联，设置触发条件（如“付款后发货”）。
  4. 设置自动任务：
    • 在“账号管理 → 自动评价与每日擦亮”中，配置自动评价文案和每日擦亮时间。
  5. 监控与客服：
    • 通过“在线聊天”集中处理所有账号的会话。
    • 根据需要配置“关键词回复”、“AI 回复”和“通知告警”（支持钉钉、飞书等）。

📋 常用配置与重要目录

  • 核心配置文件：.env（环境变量）和命令行参数。
  • 数据库连接：支持 SQLite（默认）、MySQL、PostgreSQL。生产环境推荐 PostgreSQL。
  • 数据加密密钥（XIANYU_DATA_KEY）：用于加密 Cookie、密码、令牌等敏感信息。此密钥极其重要，丢失后无法解密已有加密数据，必须与数据库备份一起妥善保管！
  • 日志与上传目录：默认在 data/ 目录下。桌面端位置见上表。

❓ 常见问题排查

  • 首次打开页面如何初始化管理员？
    启动服务后访问页面，如果数据库为空，页面会自动显示“首次设置管理员密码”的界面，填写密码即可创建 admin 用户。
  • 账号频繁掉线或需要安全验证？
    1. 查看账号管理中的状态和日志。
    2. 根据页面提示在手机闲鱼 App 完成人脸或安全验证。
    3. 避免在多个实例同时运行同一账号。
    4. 若一直提示验证，请先登录闲鱼官方网页版，人工通过风控后等待一会儿再尝试登录。
  • 修改 XIANYU_DATA_KEY 后无法读取凭证？
    这是正常的安全行为。你必须恢复使用原先的密钥。如无法恢复，只能重新登录所有账号并重新配置所有加密字段。

总结

Ydisks闲鱼助手是一个功能强大的自托管工具，但其合规性风险极高。强烈建议仅将此项目用于个人技术学习研究。如果你决定在生产或半生产环境使用，必须优先使用 Docker Compose 方式部署，并务必备份好 .env 中的 XIANYU_DATA_KEY 和 PostgreSQL 数据库。同时，务必做好账号被平台风控甚至封禁的心理准备和应对预案。