x_gift_bot README

The project's README from github.com/mizorewww/x_gift_bot. As one markdown file: README.md.

XGift

X (Twitter) Premium 礼品兑换平台。你生成兑换码发给用户，用户在网页上输入兑换码和自己的 X 用户名，系统自动完成 Premium 赠送的下单与付款。

截图

以下截图来自本地模拟预览（全部为示例数据）：

兑换页 管理页（统计概览）
兑换页 管理页 · 浅色

管理页深色模式：

管理页 · 深色

本地预览（不写任何真实配置）

想先看看界面？只需要 Node.js 22+：

npm ci
npm run build
npm run preview

打开 http://127.0.0.1:4173 是兑换页，http://127.0.0.1:4173/admin 是管理后台。所有数据都是内存示例，不连接真实服务。在兑换页输入 XG- 加 48 个字母 A 可以演示完整成功流程。

部署教程

第一步：准备这些东西

部署前请先准备好以下四样东西，配置向导会逐项询问：

  1. X 登录 Cookie（auth_token 和 ct0）：在浏览器登录 x.com 后，按 F12 打开开发者工具 → Application（应用）→ Cookies → https://x.com，复制这两项的值。这是系统以你的 X 账号身份发起赠送的凭据。
  2. 一张用于付款的银行卡：卡号、有效期、CVC，以及发卡行登记的持卡人姓名、账单邮箱和账单国家（两位代码，如 BD）。请只填真实信息。
  3. 代理（可选）：服务器能直接访问 x.com 就选「直连」；否则准备一个代理节点。支持 sing-box 的任意 outbound 类型（anytls、socks、http、shadowsocks、vmess、vless、trojan 等），也可以直接粘贴完整 sing-box 配置。
  4. Stripe 公钥：X 结账页面使用的 pk_live_ 开头公钥。使用默认 X Premium 目录时向导会说明；它与商户、商品、价格一起保存在「目录」配置中，也可以完全自定义。

另外需要：一台 Linux 服务器、一个指向该服务器的域名、服务器上安装 Go 1.27+（或在自己电脑上构建后上传二进制）。

第二步：构建

git clone https://github.com/mizorewww/x_gift_bot.git
cd x_gift_bot
npm ci && npm run build        # 构建前端（只需一次，产物已随仓库提交时可跳过）
go build -o bin/xgift ./cmd/xgift
go build -o bin/xgift-web ./cmd/xgift-web

第三步：运行配置向导

./bin/xgift setup

向导会一步步引导你完成配置，全程有中文提示：

  1. 密码文件 — 自动生成一个随机密码用于加密保管库，保存在你指定的路径（默认 sqlite/vault-password，仅本人可读）。请务必备份这个文件，丢失后所有加密数据无法恢复。
  2. X 凭据 — 粘贴第一步准备的两个 Cookie。
  3. 支付卡 — 输入卡信息和账单信息（卡号会自动校验）。
  4. 代理 — 选直连、按提示填 AnyTLS 节点，或粘贴 sing-box 配置；保存前会实际启动验证配置是否有效。
  5. Stripe 公钥 — 粘贴 pk_live_ 公钥。
  6. 商品目录 — 直接回车使用 X Premium 默认目录（3/6 个月套餐），或自定义商户、币种和套餐。
  7. 站点配置 — 输入你的域名（如 https://xp.example.com），向导会生成 site.env 和随机的后台管理员密码（只显示一次，同时保存在文件里）。

完成后运行 ./bin/xgift status，六条记录全部显示 verified 即为成功。

第四步：启动网站

把向导生成的 site.env、admin-password、vault-password 放到安全目录（生产建议 /etc/xgift/，权限 0600），然后：

sudo systemctl link $PWD/deploy/xgift.service   # 或直接复制到 /etc/systemd/system/
# 编辑 deploy/xgift.service 中的路径使其与你的安装位置一致
sudo systemctl enable --now xgift

site.env 各字段含义：

字段 说明
XGIFT_ORIGIN 站点完整域名（https:// 开头）
XGIFT_LISTEN 监听地址，只能回环，如 127.0.0.1:8787
XGIFT_DATA_DIR 数据目录（vault.db、site.db 所在）
XGIFT_PASSWORD_FILE 保管库密码文件路径
XGIFT_ADMIN_PASSWORD_FILE 后台密码文件路径
XGIFT_PAYMENTS_ENABLED true 开放充值，false 暂停（不消耗兑换码）

第五步：配置 HTTPS 反向代理

程序只监听本机端口，需要 Caddy（或任意反向代理）提供 HTTPS。deploy/Caddyfile 是模板，把 xp.example.com 替换成你的域名后放到 Caddy 配置目录并 reload 即可。模板默认只放行 Cloudflare 回源 IP，不用 Cloudflare 时删掉 @cloudflare 相关段、保留 reverse_proxy 即可。

验证：

curl https://你的域名/healthz     # {"ok":true,...} 即成功

第六步：开始使用

浏览器打开 https://你的域名/admin，输入用户名 admin 和向导生成的密码：

  1. 在「生成兑换码」选套餐、数量、批次名，点生成，复制或下载兑换码发给用户。
  2. 顶部「统计概览」随时查看兑换进度和成功率。
  3. 用户打开 https://你的域名，输入兑换码和 X 用户名即可完成充值。

日常维护

./bin/xgift status              # 检查所有加密记录是否完好
./bin/xgift check               # 测试代理能否访问 x.com
./bin/xgift import-chrome       # macOS：从本机 Chrome 重新导入 X Cookie（过期时用）

更新配置用 put（从标准输入读取新值）：

echo '新的ct0等JSON' | ./bin/xgift put --name cookies      # 还有 card / proxy / api-auth
echo 'pk_live_新公钥' | ./bin/xgift put --name stripe-key
echo '{"merchant":"acct_...","currency":"bdt","plans":[...]}' | ./bin/xgift put --name catalog

常见问题

密码文件丢了怎么办？ 无法恢复。加密数据全部作废，需要删除 vault.db 后重新运行 xgift setup。请把它和数据库一起备份。

X Cookie 过期了？ macOS 上用 ./bin/xgift import-chrome 一键刷新；其他系统重新从浏览器复制后用 put --name cookies 更新。

想暂停充值？ 把 site.env 里 XGIFT_PAYMENTS_ENABLED 改为 false 并重启服务。用户兑换会被婉拒，兑换码不消耗。

付款结果不明怎么办？ 系统宁可标记「待核实」也不会重复扣款。用户用原兑换码点「重新检查并继续兑换」即可自动核对，确认成功后自动补上状态。

升级程序？ 重新构建两个二进制，备份数据目录和密码文件，替换后 systemctl restart xgift。不要覆盖线上数据库。

数据与安全

x_gift_bot (mizorewww/x_gift_bot)

Searching Database…

1.3K ·GitHub
X_gift_bot
Что это?X Gift Bot — самостоятельно хостируемая платформа для продажи подписок X (Twitter) Premium в виде подарочных кодов: вы генерируете коды активации и раздаёте их, а пользователи активируют их на веб-странице, вводя код и своё имя пользователя X, после чего система автоматически оформляет и оплачивает заказ Premium.
Это CLI-инструмент или веб-приложение?И то, и другое: CLI-бинарник «xgift», который вы запускаете на своём Linux-сервере для настройки, проверки статуса и обновления конфигов, плюс обслуживаемое им веб-приложение — публичная страница активации для покупателей и защищённая паролем админ-панель для генерации кодов и просмотра статистики.
Как это запустить?Соберите Go-бинарники и запустите «./bin/xgift setup», который проведёт вас через пароль хранилища, куки X, платёжную карту, прокси, ключ Stripe и конфиг сайта, затем поставьте сервер за обратный прокси Caddy, используя приложенный шаблон Caddyfile, для HTTPS.
Что нужно перед развертыванием?Linux-сервер с Go 1.27+ (или бинарник, собранный в другом месте) и домен, направленный на него, плюс куки входа X (auth_token и ct0), настоящая банковская карта, публичный live-ключ Stripe и, опционально, прокси, если сервер не может напрямую достучаться до x.com.
Какой главный риск при запуске?Если потеряете файл пароля хранилища, все зашифрованные данные (куки, карта, прокси, заказы) станут навсегда невосстановимыми, придётся удалить vault.db и заново пройти настройку с нуля; куки X также истекают и требуют периодического обновления.
Как он избегает двойного списания, когда результат оплаты неясен?Заказы с неясным результатом оплаты помечаются как «ожидает проверки», а не повторяются; пользователь может нажать «перепроверить и продолжить» на том же коде для повторной проверки, и статус заказа обновится автоматически после подтверждения.
Можно ли приостановить продажи, не аннулируя выданные коды?Да, установите XGIFT_PAYMENTS_ENABLED в false в site.env и перезапустите сервис; попытки активации вежливо отклоняются, а код не расходуется.
Какие типы прокси можно использовать, если сервер не достаёт до x.com?Подойдёт любой outbound-тип sing-box — AnyTLS, SOCKS, HTTP, Shadowsocks, VMess, VLESS, Trojan — или можно вставить полный конфиг sing-box напрямую.
Можно ли попробовать интерфейс до настройки реальных аккаунтов и платежей?Да, локальный режим предпросмотра (нужен только Node.js 22+) показывает страницы активации и админки на образцах данных в памяти; ввод кода вида «XG-», за которым следуют 48 букв A, демонстрирует полный успешный сценарий.
What are similar projects?manychat-lite-cloudflare, caddy, nginx-proxy-manager, DoulorCloud, hyperswitch, CFNext, TikTokDownloader, CFBox
Which topics is it in?caddy, stripe, payments, social-media, bot, admin-dashboard, reverse-proxy, cloudflare, encryption, sqlite, proxy, dashboard
Creator
mizorewww
Size
14.9 MB
Stars
1.3K
Updated
CommitOct 09
Age
16d
Commits · 90 Days