# Brandbidding 操作指南

更新时间：2026-03-31  
适用版本：v4.x（当前线上版本）

---

## 1. 文档说明

这是一份给用户使用的完整操作手册，覆盖安装、升级、配置、投放、订阅与排障。

- 按功能区组织内容，直接对应左侧菜单。
- 每个功能标注可用版本（`Lite` / `Pro` / `Max`）。
- 每个章节都放对应截图位，你补图后我可继续自动回填。

版本标识：

- `Lite`：基础版
- `Pro`：进阶版
- `Max`：完整自动化版

---

## 2. 一键安装与升级

### 2.1 一键安装（新机器）

可用版本：`Lite` `Pro` `Max`  
用途：在空白 VPS 上一次性完成服务部署、初始化与启动。

操作路径：`SSH 登录服务器 -> 执行安装脚本`

```bash
curl -fsSL -o /tmp/install_vps.sh https://raw.githubusercontent.com/wd9337812/bbexchange-installer/main/install_vps.sh
sudo bash /tmp/install_vps.sh
```

步骤：

1. SSH 连接 VPS。
2. 执行安装脚本，等待自动完成。
3. 浏览器访问你的域名，确认可以打开登录页。

示意图（安装后页面）：  
![U-01 登录后首页（总览看板）](/manual-images/U-01.png)

### 2.2 一键升级（已部署）

可用版本：`Lite` `Pro` `Max`  
用途：在保留业务数据前提下升级到最新镜像和修复脚本。

操作路径：`SSH 登录服务器 -> 执行升级脚本`

```bash
cd /opt/brandbidding
curl -fsSL -o scripts/update_image.sh https://raw.githubusercontent.com/wd9337812/bbexchange-installer/main/scripts/update_image.sh
chmod +x scripts/update_image.sh
bash scripts/update_image.sh
```

步骤：

1. 进入项目目录。
2. 拉取并执行升级脚本。
3. 刷新浏览器并检查关键页面是否正常。

### 2.3 总后台升级（控制面）

可用版本：`Lite` `Pro` `Max`  
用途：升级订阅总后台、账单与支付控制能力（不影响租户业务数据）。

```bash
cd /opt/bbauto-control-plane
curl -fsSL -o scripts/update_control_plane_site.sh https://raw.githubusercontent.com/wd9337812/bbexchange-installer/main/scripts/update_control_plane_site.sh
chmod +x scripts/update_control_plane_site.sh
bash scripts/update_control_plane_site.sh
```

---

## 3. 订阅版本能力总览

用途：快速判断当前版本可以使用哪些功能，便于选型和升级。

| 能力 | Lite | Pro | Max |
|---|---:|---:|---:|
| 创建任务 | ✅ | ✅ | ✅ |
| 创建广告 | ❌ | ✅ | ✅ |
| 批量创建 | ❌ | ✅ | ✅ |
| 自动化策略执行 | ❌ | ❌ | ✅ |
| 飞书告警能力 | ❌ | ✅ | ✅ |
| 订阅管理与支付 | ✅ | ✅ | ✅ |

---

## 4. 页面导航与入口

用途：熟悉系统菜单结构，快速定位每个功能入口。  
操作路径：`登录后 -> 左侧菜单`

1. 总览看板
2. 任务管理
3. 联盟管理
4. 自动化
5. 系统设置（Google Ads、联盟交易同步、素材 API、告警配置、数据备份、权限管理、审计日志、系统日志、系统设置、动态 IP、订阅管理）

示意图（菜单全展开）：  
![U-02 左侧菜单全量展开（显示所有功能入口）](/manual-images/U-02.png)

---

## 5. 总览看板

可用版本：`Lite` `Pro` `Max`  
用途：查看当前投放表现和关键经营指标。  
操作路径：`左侧菜单 -> 总览看板`

步骤：

1. 点击 `总览看板`。
2. 查看“今日数据”“累计数据”。
3. 切换业务/任务视图观察变化趋势。

示意图：  
![U-03 顶部状态区（账号、退出、帮助入口）](/manual-images/U-03.png)

---

## 6. 任务管理

### 6.1 任务列表与筛选

可用版本：`Lite` `Pro` `Max`  
用途：按状态、时间、关键词等条件快速定位任务。  
操作路径：`任务管理`

步骤：

1. 设置筛选条件（状态、关键词、时间等）。
2. 点击 `查询`。
3. 点击 `重置` 清空条件。

示意图：  
![U-04 任务管理列表页（含筛选区）](/manual-images/U-04.png)

### 6.2 新建任务

可用版本：`Lite` `Pro` `Max`  
用途：创建新的投放执行单元。  
操作路径：`任务管理 -> 新增任务`

步骤：

1. 点击 `新增任务`。
2. 填写基础字段（任务名、国家、预算等）。
3. 配置投放参数。
4. 点击 `保存`。

示意图：  
![U-05 新建任务表单（基础信息区）](/manual-images/U-05.png)  
![U-06 新建任务表单（投放参数区）](/manual-images/U-06.png)

### 6.3 编辑任务

可用版本：`Lite` `Pro` `Max`  
用途：调整既有任务的预算、目标国家和执行参数。  
操作路径：`任务管理 -> 操作列 -> 编辑`

步骤：

1. 点击目标任务 `编辑`。
2. 修改字段并 `保存`。
3. 返回列表确认更新时间。

示意图：  
![U-07 编辑任务页面（关键字段修改示例）](/manual-images/U-07.png)

### 6.4 暂停/启动任务

可用版本：`Lite` `Pro` `Max`  
用途：临时停止任务或恢复任务执行。

步骤：

1. 点击 `暂停` 停止执行。
2. 点击 `启动` 恢复执行。

示意图：  
![U-08 任务暂停启动操作位置](/manual-images/U-08.png)

### 6.5 批量创建

可用版本：`Pro` `Max`  
用途：一次创建多条结构类似任务，提升建单效率。  
操作路径：`任务管理 -> 批量创建`

步骤：

1. 点击 `批量创建`。
2. 导入/填写批量参数。
3. 点击 `提交`。

示意图：  
![U-09 批量创建入口与操作区（Pro-Max）](/manual-images/U-09.png)

---

## 7. 联盟管理

### 7.1 联盟主数据

可用版本：`Lite` `Pro` `Max`  
用途：维护联盟、联盟账号、Offer 基础数据，供任务和归因调用。  
操作路径：`联盟管理 -> 联盟/账号/Offer`

步骤：

1. 进入对应子页。
2. 点击 `新增`。
3. 填写字段并 `保存`。

示意图：  
![U-10 联盟管理主页面](/manual-images/U-10.png)  
![U-12 联盟主数据（联盟账号）页面](/manual-images/U-12.png)  
![U-14 联盟主数据（Offer）页面](/manual-images/U-14.png)

### 7.2 联盟交易同步

可用版本：`Lite` `Pro` `Max`  
用途：按配置窗口主动从联盟交易 API 拉取转化/佣金状态，驱动归因与报表统计。  
操作路径：`系统设置 -> 联盟交易同步`

步骤：

1. 配置同步窗口、分页大小与联盟账号 Token。
2. 点击 `保存`。
3. 点击 `立即同步`，在“同步记录”查看每个联盟账号的拉取/入库/归因与错误信息。

示意图：  
![U-15 联盟交易同步设置页面](/manual-images/U-15.png)

### 7.3 素材 API

可用版本：`Lite` `Pro` `Max`  
用途：接入关键词/素材/AI能力，支撑创意生成和投放素材准备。  
操作路径：`系统设置 -> 素材 API`

步骤：

1. 配置关键词 API（地址、密钥、Header）。
2. 配置素材 API。
3. 配置 AI 模型（建议先用 OpenRouter 免费模型联调）。
4. 点击 `保存`。

示意图：  
![U-16 素材 API 设置页面（AI模型页签）](/manual-images/U-16.png)  
![U-17 素材 API 设置页面（关键词API页签）](/manual-images/U-17.png)

---

## 8. 自动化

### 8.1 自动化任务

可用版本：`Max`  
用途：查看每次自动化执行记录和失败原因，便于追踪问题。  
操作路径：`自动化 -> 自动化任务`

步骤：

1. 设置筛选条件。
2. 点击 `查询`。
3. 查看执行成功/失败原因。

示意图：  
![U-18 自动化任务列表页](/manual-images/U-18.png)

### 8.2 自动化策略

可用版本：`Max`  
用途：配置“条件 + 动作”规则，实现自动调参与自动治理。  
操作路径：`自动化 -> 自动化策略`

步骤：

1. 点击 `新增策略`。
2. 设置条件区。
3. 设置动作区。
4. 点击 `保存策略`。

示意图：  
![U-19 自动化策略列表页](/manual-images/U-19.png)  
![U-20 新增自动化策略弹窗（条件区）](/manual-images/U-20.png)  
![U-21 新增自动化策略弹窗（动作区）](/manual-images/U-21.png)

### 8.3 自动化全局配置

可用版本：`Max`  
用途：控制自动化的全局开关、调度周期和执行边界。

示意图：  
![U-22 自动化全局配置页面](/manual-images/U-22.png)

---

## 9. Google Ads

### 9.1 服务账号配置

可用版本：`Lite` `Pro` `Max`  
用途：授权系统访问 Google Ads API。  
操作路径：`系统设置 -> Google Ads -> 服务账号`

步骤：

1. 进入 Google Cloud Console。
2. `IAM 与管理 -> 服务账号 -> 创建服务账号`。
3. `密钥 -> 创建新密钥 -> JSON` 下载文件。
4. 回系统上传 JSON 并保存。

示意图：  
![U-23 Google Ads 服务账号页面](/manual-images/U-23.png)  
![U-24 上传服务账号 JSON 区域](/manual-images/U-24.png)

### 9.2 请求治理与 Script

可用版本：`Lite` `Pro` `Max`  
用途：治理请求频率、缓存与任务级调用质量，降低 API 风险。

示意图：  
![U-25 Google Ads 请求治理页面](/manual-images/U-25.png)  
![U-26 Google Ads Script 页面](/manual-images/U-26.png)

---

## 10. 系统设置与运维

可用版本：`Lite` `Pro` `Max`

### 10.1 告警配置（`Pro` `Max`）

用途：配置告警渠道与阈值，异常时自动通知运营。  
![U-27 告警配置页面](/manual-images/U-27.png)

### 10.2 数据备份

用途：手动触发和查看备份结果，保障可恢复能力。  
![U-28 数据备份页面](/manual-images/U-28.png)

### 10.3 权限管理

用途：按角色分配菜单和操作权限，控制账号访问范围。  
![U-29 权限管理页面](/manual-images/U-29.png)

### 10.4 审计日志

用途：追踪关键操作人、操作时间和变更内容。  
![U-30 审计日志页面](/manual-images/U-30.png)

### 10.5 系统日志

用途：统一排查任务、自动化、接口调用异常。  
![U-31 系统日志页面](/manual-images/U-31.png)

### 10.6 系统设置

用途：维护实例级基础参数和运行行为。  
![U-32 系统设置页面](/manual-images/U-32.png)

### 10.7 动态 IP

用途：配置代理与探针校验，降低 Visit 国家不匹配问题。  
![U-33 动态IP配置页面](/manual-images/U-33.png)

说明：

1. 当前已验证可稳定使用的动态 IP 服务商账号格式为 `B2proxy`（账号前缀+国家后缀拼接模式）。
2. 其他动态 IP 服务商请先在测试环境验证账号格式与探针结果，再用于生产。
3. 若出现兼容问题，请联系作者协助排查。

---

## 11. 订阅管理

### 11.1 当前状态查看

可用版本：`Lite` `Pro` `Max`  
用途：查看当前套餐、到期时间和访问状态。  
操作路径：`系统设置 -> 订阅管理`

步骤：

1. 查看当前套餐、到期时间、访问状态。
2. 查看账单记录。

示意图：  
![U-34 订阅管理页](/manual-images/U-34.png)

### 11.2 续费支付

用途：发起新支付并续费订阅，保持功能可用。

步骤：

1. 选择套餐。
2. 选择周期。
3. 选择支付方式。
4. 点击创建支付。
5. 支付后刷新状态。

### 11.3 账单记录

用途：核对每笔支付状态、到账时间和订阅区间。

---

## 12. 常见问题与排障

### Q1 页面空白或功能异常

1. 强制刷新浏览器（`Ctrl + F5`）。
2. 确认已升级到最新版本。
3. 打开控制台检查报错。
4. 在系统日志定位对应时间错误。

### Q2 支付成功但订阅未更新

1. 查看账单是否生成。
2. 检查 API Key / Webhook 配置。
3. 点击同步支付状态。

### Q3 自动化策略未执行

1. 确认当前版本是 `Max`。
2. 检查自动化任务队列。
3. 检查系统日志错误。

### Q4 Google Ads 调用失败

1. 检查服务账号 JSON。
2. 检查 Developer Token 授权。
3. 检查请求治理限流配置。

### Q5 Visit 国家不匹配（`PROXY_COUNTRY_MISMATCH`）

1. 核对任务国家和代理国家编码。
2. 在动态 IP 页面做探针测试。
3. 在系统日志比对 runtime country 与 task countries。

---

## 附录 A：订阅版本差异

### A.1 功能差异矩阵

| 功能模块 | Lite | Pro | Max |
|---|---:|---:|---:|
| 总览看板 | ✅ | ✅ | ✅ |
| 任务管理（基础） | ✅ | ✅ | ✅ |
| 广告创建能力 | ❌ | ✅ | ✅ |
| 批量创建能力 | ❌ | ✅ | ✅ |
| 联盟管理 | ✅ | ✅ | ✅ |
| Google Ads 配置 | ✅ | ✅ | ✅ |
| 告警配置 | ❌ | ✅ | ✅ |
| 自动化任务/策略 | ❌ | ❌ | ✅ |
| 订阅与账单 | ✅ | ✅ | ✅ |

### A.2 升级建议

1. `Lite -> Pro`：需要批量创建和告警能力时升级。
2. `Pro -> Max`：需要自动化策略闭环时升级。

---

## 附录 B：术语解释

1. `任务`：投放执行单元，包含国家、预算、策略等配置。
2. `换参`：系统按规则自动调整参数。
3. `自动化策略`：由条件和动作组成的规则。
4. `自动化任务`：策略命中后产生的执行记录。
5. `联盟交易同步`：系统按窗口从联盟交易 API 主动拉取转化数据。
6. `素材 API`：用于拉取/生成素材的外部接口。
7. `关键词 API`：用于获取关键词建议的外部接口。
8. `请求治理`：Google Ads 请求频率/预算/缓存控制。
9. `账单记录`：支付与订阅状态留痕。
10. `同步支付状态`：主动拉取支付结果的手动动作。