0.2.1

@0xainetoem/white-label

白标品牌注入 SDK + CLI 部署工具 —— 8 个 0xAI 生态产品的统一白标解决方案。

npm install @0xainetoem/white-label
npx wl list

📖 详细使用手册：DOCS.md — 架构总览、CI/CD 集成、Nginx 配置、故障排查、产品白标分步指南

---

解决的问题

你的客户想要自己的品牌，但部署 8 个独立产品意味着 8 套品牌配置、Nginx 配置、域名、合约部署——每次重复劳动。

white-label 做什么：

---

快速开始

1. 前端 React 项目接入（3 行）

// 入口文件：main.tsx
import { defineBrand, BrandProvider } from '@0xainetoem/white-label/react';

// 自动读取 src/branding.json
const brand = defineBrand();

createRoot(document.getElementById('root')!).render(
  <BrandProvider brand={brand}>
    <App />
  </BrandProvider>
);

2. 组件内使用品牌

import { useBrand, BrandLogo } from '@0xainetoem/white-label/react';

function Header() {
  const { brand } = useBrand(); // 自动注入的 BrandConfig
  return (
    <header style={{ backgroundColor: brand.colors.primary }}>
      <BrandLogo variant="dark" className="h-8" />
      <h1>{brand.name}</h1>
    </header>
  );
}

3. 非 React 环境（Node.js / 后端）

import { defineBrand, getBrand } from '@0xainetoem/white-label';

defineBrand({ brand: { name: 'MyChain', colors: { primary: '#ff6600' } } });
const brand = getBrand();
console.log(brand.name); // "MyChain"

---

CLI 命令

wl setup — 一键全流程（推荐）

# 进入产品目录后在运行
cd /home/ubuntu/bitbyte-v4

# 交互式生成品牌配置 + 部署合约 + 构建上传 + Nginx SSL 配置
wl setup bitbyte \
  --name "ACME DEX" \
  --color "#ff6600" \
  --server root@1.2.3.4 \
  --domain dex.acme.com \
  --chain polygon --rpc https://polygon-rpc.com --chain-id 137 \
  --key 0x_deployer_private_key

参数说明：

Ceres 特殊参数 --mode：

# 完整白标 — 部署全部合约 + 构建前端 + relay
wl setup ceres --name "Client" --mode full --server root@1.2.3.4

# 轻量白标 — 仅部署 DID + Registry 合约，复用 Ceres 品牌
wl setup ceres --name "DID Client" --mode light --rpc <url> --key <pk>

wl brand — 交互式生成 branding.json

cd /home/ubuntu/zenonft
wl brand
# → 交互式输入：品牌名、简称、主色、Logo URL、域名、邮箱
# → 生成 ./branding.json

wl deploy — 构建 + 上传

# 进入产品目录后在执行
wl deploy         # 自动检测项目

# 或指定产品
wl deploy bitbyte --server root@1.2.3.4 --domain dex.acme.com

# 构建流程（因产品而异）：
#   bitbyte    → 4 个前端 (Max/Flash/Admin/Landing) → rsync
#   oxachain   → make geth + make docker → ./deploy-l1.sh
#   cryptchat  → client + server → rsync
#   predx      → frontend-wagmi → rsync
#   bridge     → frontend-bridge → rsync
#   zenonft    → frontend → rsync
#   ceres      → frontend-v2 → rsync

wl deploy-contracts — 部署智能合约

# cryptchat 无合约（共享基础设施），其他 7 个项目都需要
wl deploy-contracts zenonft --rpc https://rpc.chain.com --key 0x_private_key --verify

# Ceres 特殊模式
wl deploy-contracts ceres --rpc <url> --key <pk>          # light（默认）
wl deploy-contracts ceres --rpc <url> --key <pk> --full   # 完整部署

# oxachain 部署 L1 链
wl deploy-contracts oxachain

部署方式（因产品而异）：

wl update — 更新部署

# 重新构建 + 重新上传（不覆盖 branding.json 和合约）
wl update bitbyte --server root@1.2.3.4

wl list — 查看可用产品和当前检测

wl list

# 输出:
#   可白标部署的产品:
#     bitbyte      — DEX (Flash + Max 双版本)
#     zenonft      — NFT 市场
#     ...
#
#   ✓ 当前项目: bitbyte
#     品牌: ACME
#     链: oxachain (Chain ID: 19505)

---

branding.json 完整格式

{
  "brand": {
    "name": "客户品牌名",
    "shortName": "ACME",
    "logo": {
      "dark": "https://cdn.客户.com/logo-dark.svg",
      "light": "https://cdn.客户.com/logo-light.svg",
      "favicon": "https://cdn.客户.com/favicon.ico"
    },
    "colors": {
      "primary": "#ff6600",
      "primaryHover": "#e55d00",
      "secondary": "#1a1a2e",
      "accent": "#00d4aa"
    },
    "domain": "客户.com",
    "contactEmail": "support@客户.com",
    "social": {
      "twitter": "https://x.com/客户",
      "discord": "https://discord.gg/客户",
      "telegram": "https://t.me/客户"
    }
  },
  "chain": {
    "network": "mainnet",
    "rpcUrl": "https://rpc.客户.com",
    "chainId": 8888,
    "explorerUrl": "https://explorer.客户.com",
    "nativeToken": "TICKER"
  },
  "features": {
    "modules": ["swap", "perpetual"],
    "enabledChains": ["ethereum", "bsc"]
  }
}

项目特有字段

OxaChain 额外字段：

{
  "consensus": {
    "type": "clique",
    "period": 30,
    "epoch": 30000,
    "blockRewardWei": "0",
    "signerCount": 7
  },
  "token": {
    "name": "MyChain Token",
    "symbol": "MCT",
    "decimals": 18,
    "initialAllocWei": "100000000000000000000000"
  },
  "deploy": {
    "imageName": "mychain/geth",
    "imageTag": "latest",
    "containerPrefix": "mychain",
    "networkName": "mychain",
    "binaryName": "mychain-geth",
    "buildTarget": "mychain"
  }
}

Ceres 额外字段：

{
  "mode": "full",
  "contracts": {
    "deployAll": true
  }
}

轻量模式：

{
  "mode": "light",
  "contracts": {
    "deployAll": false,
    "only": ["CeresDID", "CeresRegistry"]
  }
}

---

React API

BrandProvider

挂载后自动执行 3 个副作用：

import { BrandProvider } from '@0xainetoem/white-label/react';

<BrandProvider brand={brand}>
  <App />
</BrandProvider>

useBrand()

import { useBrand } from '@0xainetoem/white-label/react';

function Footer() {
  const { brand } = useBrand(); // BrandConfig
  return (
    <footer>
      <p>© {brand.name}</p>
      <p>联系: {brand.contactEmail}</p>
    </footer>
  );
}

BrandLogo

import { BrandLogo } from '@0xainetoem/white-label/react';

// 深色背景用 light 变体
<BrandLogo variant="light" className="h-8" />
// 浅色背景用 dark（默认）
<BrandLogo variant="dark" />

---

非 React API

import { defineBrand, getBrand } from '@0xainetoem/white-label';
import { injectCSSVars, injectFavicon, injectMeta } from '@0xainetoem/white-label';

// 设置品牌（全局单例）
const brand = defineBrand({
  brand: { name: 'MyBrand', colors: { primary: '#ff6600' } }
});

// 读取品牌
const current = getBrand();

// 手动注入副作用（React 项目由 BrandProvider 自动处理）
injectCSSVars(current);   // CSS 变量 → :root
injectFavicon(current);   // Favicon → <link>
injectMeta(current);      // Meta → <head>

---

CSS 变量对照表

Tailwind 中使用：

/* tailwind.config.js 或 global.css */
@layer base {
  :root {
    --brand-primary: #3b82f6; /* 会被 BrandProvider 覆盖 */
  }
}

<div className="bg-[var(--brand-primary)] text-white">
  Branded Content
</div>

---

SDK 集成包装器

7 个产品 SDK 已集成品牌注入包装器：

示例：

import { defineBrand } from '@0xainetoem/white-label';
import { createOxaChainClient } from '@0xainetoem/white-label/oxachain';

defineBrand({ brand: { name: 'MyChain', colors: { primary: '#ff6600' } } });
const client = createOxaChainClient({ rpcUrl: 'http://localhost:18545' });
console.log(client.getBrand().name); // "MyChain"

注意：这些 SDK 是可选依赖（peerDependenciesMeta.optional=true），需项目中额外 npm install 对应 SDK 包。如果 SDK 尚未发布到 npm（如 @0xaibridge/sdk），SDK 包装器会优雅降级并提示安装。

---

OxaChain 公链白标（高级用法）

OxaChain 是特殊的白标产品——底层的 Geth 节点也需要品牌化改造。

# 生成品牌链配置
wl setup oxachain \
  --name "Acme Chain" --color "#ff6600" \
  --server root@1.2.3.4 --domain acme.io

# 或手动使用 Makefile
make build BRANDING_FILE=branding.json
# → 自动执行 6 项 Geth 源码改造：
#   1. 原生代币名/符号
#   2. Chain ID
#   3. 出块时间 (Clique)
#   4. 区块奖励（0 = 关闭）
#   5. 初始代币分配
#   6. 启动节点 signer 密钥

# 部署 L1 链
./deploy-l1.sh
# → 8 步自动化：signer 密钥 → genesis → Docker build → 启动 → 健康检查

自动生成的 Go 源码文件：

build/geth-patch/
├── branding.mk               # Makefile 参数
├── apply-patch.sh             # 应用到 geth-src
├── apply-block-reward.py      # 区块奖励注入
├── oxachain-l1.patch
└── src/
    ├── params/{brand}chain_config.go
    ├── core/{brand}chain_genesis.go
    └── cmd/utils/{brand}chain_flags.go

---

Ceres 双模式白标

# 完整白标
wl setup ceres --name "Client" --mode full \
  --server root@1.2.3.4 --domain client.com \
  --rpc https://rpc --key 0x_key

# 轻量白标
wl setup ceres --name "DID Client" --mode light \
  --rpc https://rpc --key 0x_key

---

目录结构

white-label/
├── bin/wl.js                           # CLI 入口
├── src/
│   ├── index.ts                        # 主入口（export 核心 API）
│   ├── types.ts                        # BrandConfig 类型 + defineBrand/getBrand
│   ├── react/index.tsx                 # BrandProvider / useBrand / BrandLogo
│   ├── cli/
│   │   ├── index.ts                    # CLI 全部实现（~540 行）
│   │   └── types.ts                    # CLI 类型
│   ├── integrations/
│   │   ├── bitbyte.ts                  # @bitbytev4/sdk 包装器
│   │   ├── predx.ts                    # @0xpredx/sdk 包装器
│   │   ├── ceres.ts                    # @ceresv2/sdk 包装器
│   │   ├── bridge.ts                   # @0xaibridge/sdk 包装器
│   │   ├── oxachain.ts                 # oxachain-sdk 包装器
│   │   ├── cryptchat.ts                # @cryptchat/sdk 包装器
│   │   └── zenonft.ts                  # @zenonft/sdk 包装器
│   ├── utils/
│   │   ├── css-vars.ts                 # CSS 变量注入
│   │   ├── favicon.ts                  # Favicon 替换
│   │   └── meta.ts                     # Meta 标签替换
│   └── templates/
│       └── branding.json               # branding.json 模板
├── package.json                        # @0xainetoem/white-label
├── tsconfig.json                       # TypeScript 配置
└── README.md

---

类型

import type { BrandConfig } from '@0xainetoem/white-label';

interface BrandConfig {
  brand: {
    name: string;
    shortName: string;
    logo: {
      dark: string;    // 深色背景 Logo URL
      light: string;   // 浅色背景 Logo URL
      favicon: string; // Favicon URL
    };
    colors: {
      primary: string;       // 主品牌色
      primaryHover: string;  // Hover 状态色
      secondary: string;     // 辅助色
      accent: string;        // 强调色
    };
    domain: string;
    contactEmail: string;
    social: {
      twitter: string;
      discord: string;
      telegram: string;
    };
  };
  chain: {
    network: 'mainnet' | 'testnet';
    rpcUrl: string;
    chainId: number;
    explorerUrl: string;
    nativeToken: string;
  };
  features: {
    modules: string[];
    enabledChains: string[];
  };
}

---

发布到 npm

当前版本：v1.0.2（已发布）

npm run build                    # TypeScript 编译
npm publish                     # 发布 @0xainetoem/white-label

注意：publishConfig.access = "public"（scoped 包需要）。包体积约 27.5 kB（压缩）/ 108.5 kB（解压），共 63 个文件。

---

许可证

MIT — 0xAI Ecosystem