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 工具还是网页应用？两者都是：一个 “xgift” CLI 二进制文件，可在你自己的 Linux 服务器上运行，用于设置、状态检查和配置更新；还有它所服务的网页应用——面向买家的公开兑换页面，以及带密码保护的管理仪表盘，用于生成兑换码和查看统计。
怎么让它跑起来？构建 Go 二进制文件并运行 “./bin/xgift setup”，它会引导你设置保险库密码、X cookies、支付卡、代理、Stripe 密钥和站点配置，然后使用自带的 Caddyfile 模板把服务器放到 Caddy 反向代理后面以启用 HTTPS。
部署之前需要准备什么？一台装有 Go 1.27+ 的 Linux 服务器（或使用在别处构建好的二进制文件），以及一个指向它的域名，外加 X 登录 cookies（auth_token 和 ct0）、一张真实的银行卡、一个 Stripe 线上公钥；如果服务器无法直接访问 x.com，还需要可选的代理。
运行它最大的风险是什么？如果丢失保险库密码文件，所有加密数据（cookies、银行卡、代理、订单）都将永久无法恢复，你必须删除 vault.db 并从头重新运行设置；此外 X cookies 会过期，需要定期刷新。
支付结果不明确时它如何避免重复扣款？支付结果不明确的订单会被标记为“待核实”而不是直接重试；用户可以在同一兑换码上点击“重新核查并继续”再次验证，确认后订单状态会自动更新。
可以暂停销售而不让已发放的兑换码失效吗？可以，在 site.env 中把 XGIFT_PAYMENTS_ENABLED 设为 false 并重启服务；兑换请求会被礼貌拒绝，兑换码不会被消耗。
如果服务器访问不了 x.com，可以用哪些代理类型？任何 sing-box 出站类型都可以——AnyTLS、SOCKS、HTTP、Shadowsocks、VMess、VLESS、Trojan——或者你也可以直接粘贴完整的 sing-box 配置。
在配置真实账号和支付之前能先试试 UI 吗？可以，本地预览模式（只需 Node.js 22+）会用内存中的示例数据展示兑换页面和管理页面；输入形如 “XG-” 后接 48 个字母 A 的兑换码即可演示完整的成功流程。
What are similar projects?manychat-lite-cloudflare, caddy, nginx-proxy-manager, DoulorCloud, hyperswitch, CFNext, numa, 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
17d
Commits · 90 Days