# tokenbar

**Repository Path**: zuohangxu/tokenbar

## Basic Information

- **Project Name**: tokenbar
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: codex/token-bar-social
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# token.agi.bar

一个连接 Token Bar API 的像素风公共池前端。用户可以注册/登录、查看后端提供的公共池与今日打赏榜、领取当前会话的 `tb_` Key，并提交固定金额的打赏申请；申请只有在管理员人工确认后才会计入公共池。

后端源码位于 Git 分支 `feat/token-bar-backend-foundation` 的 `server/` 目录；本工作区对应路径是 `.worktrees/backend-foundation/server`。发布时需要同时准备该分支的 Go 服务和 `main` 分支构建出的前端 `dist/`，两者通过同一个 HTTPS origin 提供服务。

腾讯云 CVM 的 Ubuntu 发布步骤见 [`docs/tencent-cloud-ubuntu-deploy.md`](./docs/tencent-cloud-ubuntu-deploy.md)。

## 运行

```bash
npm install
npm run dev
```

打开 [http://localhost:5173](http://localhost:5173)。

也可以使用生产预览：

```bash
npm run build
npm run preview -- --host 127.0.0.1
```

## 当前边界

- 当前 MVP 只开放 DeepSeek 公共池与 `/v1` 网关；前端不再把本地 mock 余额或本地打赏写入公共池事实。
- 打赏金额固定为 ¥1、¥5、¥10、¥50、¥100、¥1000，分别显示为「抿一口」「提一杯」「请一巡」「摆一桌」「包全场」「立金樽」。提交后显示 `PENDING`，管理员确认后才会进入公共池。
- 成员 Key 只在当前页面内存中接收明文；连接卡默认只显示掩码，刷新后只显示前缀/已有状态。
- 不包含自动支付、自动审核、流式多供应商路由或客户端持久化 Key。数据库、Redis、DeepSeek Key 与 Session 密钥只由后端环境文件管理。

## 检查

```bash
npm run lint
npm run typecheck
npm test -- --run
npm run build
npm run test:e2e
```

Playwright 使用本地 Chromium，默认校验响应式、键盘、无外网请求、安全边界和像素样式契约。截图基线默认不生成；需要明确批准时使用 `PW_APPROVED_SNAPSHOTS=1 npm run test:e2e`。

## 生产部署

生产入口由 Nginx 提供 HTTPS：静态前端从 `/var/www/token-bar/current/dist` 读取，`/api/` 和 `/v1/` 反向代理到本机 Go 服务的 `127.0.0.1:3000`。配置示例见 [`deploy/nginx/token-bar.conf.example`](./deploy/nginx/token-bar.conf.example)。浏览器只需要构建时的 `VITE_TOKEN_BAR_API_ORIGIN`；DeepSeek Key、Session 密钥、数据库和 Redis 凭据只能放在后端未跟踪的环境文件中。

### 首次发布

下面的示例使用按版本保留的目录，便于快速回滚。请先准备 DNS、TLS 证书、PostgreSQL、Redis、SMTP 设置和一个仅运行 Go 服务的系统用户。前端 `main` checkout 与后端 `feat/token-bar-backend-foundation` checkout 需要并列准备；将 `TOKEN_BAR_BACKEND_ROOT` 设为后端 checkout 的绝对路径。构建前端需要 Node.js `20.19+` 或 `22.12+`，构建后端需要 Go `1.25.1+`。

```bash
# 1. 构建静态前端（不要把后端密钥写入 .env.example 或 Vite 变量）
backend_root="${TOKEN_BAR_BACKEND_ROOT:?set TOKEN_BAR_BACKEND_ROOT to the backend checkout}"
test -f "$backend_root/server/.env.tokenbar.example"
cp .env.example .env.production
# 编辑 .env.production，设置实际的 VITE_TOKEN_BAR_API_ORIGIN
npm ci
npm run build

# 2. 在目标服务器 staging 后上传到新的版本目录，再切换 current
release="$(date -u +%Y%m%d%H%M%S)"
staging="$(mktemp -d /var/tmp/tokenbar-dist.XXXXXX)"
sudo chown tokenbar:tokenbar "$staging"
sudo chmod 0755 "$staging"
sudo -u tokenbar rsync -a --delete dist/ "$staging/"
sudo install -d -o tokenbar -g tokenbar "/var/www/token-bar/releases/$release/dist"
sudo -u tokenbar rsync -a --delete "$staging/" "/var/www/token-bar/releases/$release/dist/"
sudo rm -rf "$staging"
next_frontend="/var/www/token-bar/current.$release.next"
sudo ln -s "/var/www/token-bar/releases/$release" "$next_frontend"
sudo mv -Tf "$next_frontend" /var/www/token-bar/current

# 3. 安装并校验后端环境（systemd 由 root 读取 EnvironmentFile，模式 0600）
sudo install -d -m 0750 /etc/token-bar
sudo install -m 0600 "$backend_root/server/.env.tokenbar.example" /etc/token-bar/tokenbar.env
# 编辑 /etc/token-bar/tokenbar.env，替换每一个占位值和实际域名
sudo bash scripts/check-tokenbar-env.sh --env-file /etc/token-bar/tokenbar.env

# 4. 编译并安装 Go 服务；TOKEN_BAR_ENV=production 会强制 HTTPS Cookie/origin
(cd "$backend_root/server" && GOWORK=off go build -o /tmp/token-bar-server .)
# systemd 单元使用 /opt/token-bar/current；让后端也按版本切换
sudo install -d -o tokenbar -g tokenbar "/opt/token-bar/releases/$release/logs"
sudo install -o tokenbar -g tokenbar -m 0755 /tmp/token-bar-server "/opt/token-bar/releases/$release/new-api"
next_backend="/opt/token-bar/current.$release.next"
sudo ln -s "/opt/token-bar/releases/$release" "$next_backend"
sudo mv -Tf "$next_backend" /opt/token-bar/current
sudo install -m 0644 "$backend_root/server/new-api.service" /etc/systemd/system/tokenbar.service
sudo systemctl daemon-reload
sudo systemctl enable --now tokenbar.service

# 5. 迁移由 master 实例启动时自动执行；先备份 PostgreSQL，再观察迁移日志
sudo journalctl -u tokenbar.service -n 100 --no-pager
sudo nginx -t && sudo systemctl reload nginx
curl --fail --silent --show-error https://tokenbar.example.com/api/status
```

后端 checkout 的 `server/model` 生产启动路径会按依赖顺序执行 Token Bar 表迁移；没有独立的“跳过迁移”开关。多实例部署时只让一个 master 执行迁移，并在备份完成后再重启服务。检查器要求环境文件显式写入 `TOKEN_BAR_ENV`；本地开发将其设置为 `development`（不要依赖命令行旧环境值覆盖 `--env-file`），例如：

```bash
# .env.local must contain TOKEN_BAR_ENV=development
bash scripts/check-tokenbar-env.sh --env-file .env.local
```

邮箱验证码使用后端现有 SMTP 配置（管理员设置中的 SMTP Server、Port、SSL/STARTTLS、Account、From、Token），这些值不在环境示例中；首次开放注册前必须配置并实发一封测试邮件。当前生产 Nginx 的 `/` 提供 Token Bar 主页面，不包含 New API 管理 Web；需要通过受限的 New API 管理入口访问 `/system-settings/operations/email`，或使用 root 会话调用 `PUT /api/option/` 更新这些选项。SMTP Token 不要写入前端环境文件。公共池打赏审批在本 MVP 中仍由管理员通过受保护的 `/api/tokenbar/admin/contribution-requests` 接口完成，未审批的申请不会入池。

### 健康检查、回滚与日志

- 健康检查先执行 `curl --fail https://tokenbar.example.com/api/status`，再查看 `journalctl -u tokenbar.service` 是否有数据库/Redis/网关就绪错误；不要把 DeepSeek Key 放进 URL、Header 或监控脚本。
- 回滚前端时，将 `/var/www/token-bar/current` 原子切回上一版 `releases/<timestamp>`，然后 `sudo systemctl reload nginx`。回滚后端时将 `/opt/token-bar/current` 切回对应的 `releases/<timestamp>`（其中包含 `new-api` 和 `logs/`），再 `sudo systemctl restart tokenbar.service`；数据库迁移通常向前兼容，降级前必须确认备份和迁移兼容性。
- Nginx 日志默认在 `/var/log/nginx/access.log`、`/var/log/nginx/error.log`；Go 服务日志在 `journalctl -u tokenbar.service`，若启用应用文件日志则位于服务工作目录下的 `logs/`。日志中不得出现验证码、Session/成员 Key 或 DeepSeek Key 明文。
- 每次发布前运行 `git diff --check`、环境检查器、`npm run build` 和 `nginx -t`；实际服务器发布仍需要运维人员提供域名、SSH 权限和生产密钥，本地构建不会替代线上部署。

## 字体

界面使用本地托管的 Fusion Pixel Font v2026.07.20（中文 proportional、英文/数字 monospaced），授权为 SIL Open Font License 1.1。许可证、来源和 SHA-256 记录见 [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)。