TanStack Ship 2026 部署指南：30分钟从零到生产环境

# 需要 Node.js 18+
node --version  # Should be >= 18.0.0

# Cloudflare Wrangler CLI
npm install -g wrangler

# 验证 Wrangler 安装
wrangler --version

# Git 版本控制
git --version

# 交互式认证
wrangler login

# 验证认证状态
wrangler whoami

# 克隆 TanStack Ship
git clone https://github.com/tanstack/ship.git
cd ship

# 安装依赖
npm install

# 验证安装
npm run dev

# wrangler.toml
name = "your-saas-name"
main = "src/entry-server.tsx"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist/client"

[[d1_databases]]
binding = "DB"
database_name = "your-db-name"
database_id = "your-database-id"

# .dev.vars - 本地开发
DATABASE_URL=file:local.db
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
AUTH_SECRET=your-auth-secret-min-32-chars

# 设置生产密钥
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET
wrangler secret put AUTH_SECRET

# 设置公开变量
wrangler secret put PUBLIC_APP_URL=https://your-domain.com

# 创建新的 D1 数据库
wrangler d1 create your-saas-db

# 返回包含用于配置的 database_id
# 稍后请保存此信息

-- schema.sql
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  stripe_customer_id TEXT,
  subscription_tier TEXT DEFAULT 'free',
  created_at INTEGER DEFAULT (unixepoch()),
  updated_at INTEGER DEFAULT (unixepoch())
);

CREATE TABLE subscriptions (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  stripe_subscription_id TEXT UNIQUE,
  status TEXT NOT NULL,
  current_period_end INTEGER,
  cancel_at_period_end INTEGER DEFAULT 0,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_subscriptions_user ON subscriptions(user_id);

# 应用 schema 到本地数据库
wrangler d1 execute your-saas-db --local --file=./schema.sql

# 应用 schema 到生产数据库
wrangler d1 execute your-saas-db --remote --file=./schema.sql

// src/routes/api/webhooks/stripe.ts
import { Router } from 'itty-router';
import { handleStripeWebhook } from '@tanstack/stripe';

const router = Router();

router.post('/webhooks/stripe', async (request, env) => {
  const signature = request.headers.get('stripe-signature');
  
  if (!signature) {
    return new Response('Missing signature', { status: 400 });
  }

  try {
    const event = await handleStripeWebhook(request, env);
    
    switch (event.type) {
      case 'checkout.session.completed':
        await handleCheckoutCompleted(event.data.object, env);
        break;
      case 'customer.subscription.updated':
        await handleSubscriptionUpdated(event.data.object, env);
        break;
      case 'customer.subscription.deleted':
        await handleSubscriptionDeleted(event.data.object, env);
        break;
    }

    return new Response(JSON.stringify({ received: true }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (err) {
    console.error('Webhook error:', err);
    return new Response('Webhook error', { status: 400 });
  }
});

export { router };

# 安装 Stripe CLI
brew install stripe/stripe-cli/stripe

# 登录 Stripe
stripe login

# 将 Webhook 转发到本地开发环境
stripe listen --forward-to localhost:8787/api/webhooks/stripe

# 复制 Webhook 签名密钥
# 添加到 .dev.vars 文件中

name: Deploy TanStack Ship

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build application
        run: npm run build

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy

# 配置自定义域名
wrangler route create --pattern=yourdomain.com --zone-id=your-zone-id

# 或使用子域名
wrangler route create --pattern=app.yourdomain.com --zone-id=your-zone-id

# 追踪生产日志
wrangler tail

# 按特定模式过滤
wrangler tail --format=pretty --watch

// src/lib/analytics.ts
import * as Sentry from '@sentry/cloudflare';

Sentry.init({
  dsn: import.meta.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
});