用户控制台定制开发指南

本文档面向二次开发者，介绍 JXWAF 云 WAF 用户控制台（jxwaf_user_console）的架构、部署对接、接口集成与二次开发方法。用户控制台为开源项目，企业可基于本指南自行定制或二次开发。

管理控制台（IT 运维团队）的操作请参考 操作指南（管理控制台），管理控制台对外自动化 API 请参考 API 调用。

一、产品定位

用户控制台是 JXWAF 云 WAF 面向 业务部门（子账号） 的自助管理平台，采用 Vue3 前端 + Go 后端 的薄代理架构：

• **Go 后端不负责业务数据存储，仅负责「会话管理 + 反向代理」，将所有业务请求转发至管理控制台的 /user/ API
• 所有业务数据存储在管理控制台，用户控制台本身不含数据库表结构（MySQL 仅为可选回退，见 部署配置）
• 新增业务功能时，需先确认管理控制台是否已提供对应 /user/ 接口

浏览器 ──► 用户控制台 Go 后端 ──(双 Token)──► 管理控制台 /user/ API
            │ 本地路由 /api/*（仅会话 + CDN 预热/刷新）
            └─ 会话(Cookie) / 登录注册 / 静态资源

二、技术栈与目录结构

技术栈

目录职责

jxwaf_user_console/
├── main.go                 入口：加载配置、装配路由、托管静态资源
├── internal/
│   ├── config.go           环境变量 → ServerConfig（必填校验）
│   ├── cloudapi.go         CloudClient：Post/PostWithMainAuth，双 Token 鉴权
│   ├── handlers.go         【核心】所有 /api/* 路由注册与代理逻辑
│   ├── session.go          SessionStore：内存会话 + Cookie + TTL 清理
│   ├── database.go         可选 MySQL：GetSubWafAuth / GetUserNameByWafAuth
│   └── response.go         统一响应：FailResponse / SuccessResponse / RawResponse
├── front-end/
│   └── src/
│       ├── main.js         入口（注册 Element Plus + 图标）
│       ├── App.vue         布局（侧边栏菜单 + Header），登录/注册页独立布局
│       ├── router/index.js 路由表（meta.requiresAuth 控制访问）
│       ├── views/          页面组件（文件名 = 功能名，如 domain.vue）
│       ├── components/     公共组件（MatchConditionBuilder.vue 等）
│       └── assets/scripts/common.js   JXAjax 请求封装、校验函数、工具函数
└── static/                 前端构建产物（勿手改，由 build.sh 生成）

三、部署与配置

3.1 前置条件

1. 已部署管理控制台，并完成：
   • 创建网站接入配置（记录配置名，见 操作指南（管理控制台））
   • 开启环境变量 USER_API_ENABLE=true（用户控制台需要管理控制台的 /user/ API）
2. 获取主账号 waf_auth（管理控制台 系统管理 → 基础配置 查看）

3.2 环境变量

3.3 部署步骤

# 1. 克隆仓库（也可通过 wget 下载源码包：wget https://github.com/jx-sec/jxwaf/archive/refs/heads/master.zip）
git clone --depth=1 https://github.com/jx-sec/jxwaf.git

# 2. 进入用户控制台目录，修改配置后启动
cd jxwaf/Cloud/jxwaf_cloud_user/
vim docker-compose.yml
docker compose up -d

部署完成后访问 http://<服务器IP>，业务部门即可注册账号并登录使用。

四、认证与会话机制

4.1 双层鉴权

用户控制台与管理控制台之间采用双层 Token 认证。/user/ 业务接口透传时，Go 后端自动注入两个请求头（开发者无需在前端请求中传递）：

jxwaf-waf-auth:      <主账号 waf_auth>（来自 CLOUD_API_KEY 配置）
jxwaf-sub-waf-auth:  <子账号 waf_auth>（来自登录会话）

鉴权流程（由管理控制台执行）：

1. 通过 jxwaf-waf-auth 反查主账号 user_name
2. 通过 jxwaf-sub-waf-auth 反查子账号 sub_user_name 及其所属主账号
3. 校验子账号归属与主账号一致（防 Token 错配）
4. 业务逻辑使用 user_name + sub_user_name 作为数据隔离键

4.2 本地会话

• 登录成功后，Go 后端创建内存 Session 并写入 Cookie jxwaf_user_session（HttpOnly，TTL 24h，每次访问滑动续期）
• SessionStore 为内存实现，重启即失效，不可横向扩展。如需集群部署，可自行替换为 Redis 等外部存储（修改 internal/session.go）

五、本地 API 接口（/api/*）

用户控制台后端对外暴露少量本地接口，分为会话类与CDN 预热/刷新类。所有接口均为 POST + application/json。

5.1 会话类接口

登录流程：调用管理控制台 /user/sub_account_login（仅需主账号鉴权）→ 成功取 waf_auth → 创建本地 Session → 写 Cookie → 返回 {result, message, waf_auth}

注册流程：自动注入 website_access_conf = DEFAULT_WEBSITE_ACCESS_CONF → 调用管理控制台 /user/sub_account_register → 不创建会话（注册成功跳登录页）

OTP 二维码密钥由 Go 本地 crypto/rand 生成（/api/get_otp_qr_url），不透传管理控制台。

5.2 CDN 预热 / 刷新接口

Go 后端将本地路径映射为管理控制台 /user/ 缓存接口后透传：

六、管理控制台 User API 集成（/user/*）

用户控制台的所有业务接口通过 POST /user/<接口名> 透传至管理控制台，路径与参数完全一致。以下为各业务模块的接口清单与关键参数。

6.1 统一响应格式

管理控制台响应经后端原样透传，四种格式：

分页约定：列表类接口 pageSize 固定 50；攻击事件/日志查询/业务明细固定 20。

6.2 账号与辅助

6.3 域名管理

create_domain 参数说明：

get_domain_list 返回 records 字段：

创建域名时，系统自动生成 CNAME 接入值。若部门已在用户控制台配置 DNS 自动接入，系统自动在 DNS 服务商创建 CNAME 记录，无需手动操作。

6.4 Web 安全防护

Web 引擎：

• protection_mode：learn（模型训练）/ business_priority（日常防护）/ security_priority（重保防护）/ offline（离线防护）
• unknown_request：未知请求处置（pass 放行 / block 拦截）
• engine_protection：语义分析防护（on 开启 / watch 观察 / off 关闭）

Web 规则 / Web 白名单（各 7 个，结构一致）：

• Web 规则 rule_action：block（阻断请求）/ watch（观察模式）
• Web 白名单 rule_action：web_white（Web 安全防护加白）/ watch（观察模式）
• rule_matchs 为匹配条件 JSON，前端必须使用 MatchConditionBuilder 组件构建，禁止手填 JSON

网页防篡改（8 个）：参数同 Web 规则，额外字段 cache_page_url, cache_page_content, cache_content_type；另有 /user/waf_get_cache_page_url（cache_page_url）用于抓取页面内容。

6.5 流量安全防护

流量引擎：

• protection_plan：daily_observe（日常观察）/ daily_protect（日常防护）/ attack_protect（攻击防护）/ emergency_protect（紧急防护）
• plans_config：各子模块（IP访问限制/IP数量限制/域名访问限制/SSL指纹防护/无差别紧急防护）的详细预案配置 JSON

流量规则 / 流量白名单（各 7 个，结构一致）：

• 流量规则 rule_action：block（阻断请求）/ reject_response（拒绝响应）/ watch（观察模式）/ bot_check（人机识别）/ network_block（网络封禁）
• stat_time：统计时间窗口（秒）；entity：统计对象；exceed_count：请求次数阈值；block_time：处罚持续时间（秒）

IP 区域封禁：

• check_model：white（白名单模式）/ black（黑名单模式）
• block_action：block / reject_response / watch / bot_check

6.6 SSL 证书

request_wildcard_cert 参数说明：

证书状态：success（已签发）/ pending（申请中）/ failed（申请失败）/ custom（已上传）/ none（未申请）。

6.7 CDN 缓存

缓存开关：

缓存策略 / 不缓存策略 / 缓存绕过策略（各 7 个，CRUD + 状态 + 优先级，结构同规则）。缓存策略额外含 cache_key（JSON 数组串，如 [{"key":"http_args","value":"path"}]）。

预热/刷新任务接口见 5.2 CDN 预热/刷新接口。

6.8 安全运营（SOC）

攻击事件 / 日志：

Web/Flow 攻击统计（各 10 个）：get_<web|flow>_attack_count_total / _count_trend / _api_count_total / _ip_count_total / _isocode_count_total / _api_top / _type_top / _ip_top / _isocode_top / _geoip，请求参数均为 from_time, to_time, domain(可选)。

count_total 系列返回环比结构：{"result": true, "message": {"current": 1500, "previous": 1200, "trend": "up"}}

业务数据统计（数据源 MySQL，按子账号隔离，sub_user_name 由会话确定）：

overview 响应字段：total_request, traffic_in, traffic_out, status_2xx, status_3xx, status_4xx, status_5xx, request_latency_avg, upstream_latency_avg, status_detail。

SOC 接口需主账号在管理控制台开启日志远程上报与安全报表配置。

七、前端定制开发

7.1 请求封装 JXAjax

所有后端请求必须走 assets/scripts/common.js 导出的 JXAjax，禁止裸用 axios：

import { JXAjax } from '../assets/scripts/common'

JXAjax('post', '/user/get_domain_list', { page: 1 },
  function (response) {
    // 成功：response.data 已保证 result === true
    // 列表接口数据在 response.data.records / total_records
  },
  function () {
    // 失败：已自动弹出错误提示，这里做业务回滚即可
  }
)

JXAjax 内置行为（不要重复实现）：

• 自动判断 result === true 为成功
• 自动弹出成功/失败 ElMessage（messageStatus: 'no-message' 可静默）
• 认证失效自动跳转登录页
• 登录成功（/api/login）自动写本地登录态

7.2 匹配条件组件

涉及 rule_matchs 的页面必须使用 components/MatchConditionBuilder.vue（可视化匹配条件构建器），禁止让用户直接编辑 JSON。

7.3 新增前端页面（标准流程）

1. 在 views/ 创建页面文件（参考同类已有页面，如 web-rule-protection.vue）
2. 在 router/index.js 注册路由（meta: { requiresAuth: true }）
3. 在 App.vue 侧边栏菜单添加菜单项
4. 调用接口：业务接口直接 JXAjax('post', '/user/<接口名>', ...)，本地会话/预热刷新类才用 /api/*
5. 校验：npm run dev 手测 + npm run build 确认无编译错误

7.4 开发约定

1. 命名：文件/函数/接口与管理控制台接口名保持一致；Go 函数用驼峰，前端文件用小写连字符
2. 禁止暴露内部字段：用户界面不得出现 jxwaf_devid、waf_node_uuid、user_name 等内部字段，需映射为中文标签
3. 产品名：界面统一显示 JXWAF（全大写）
4. UI 一致性：复用 Element Plus 组件与既有页面的布局/间距/配色；统计类图表用折线图，单位与数值直接关联
5. 不添加未要求的功能：只实现任务要求的页面/接口，不擅自加菜单或功能

八、后端定制开发

8.1 两种代理模式

8.2 新增接口流程

业务接口（绝大多数情况）：

1. 确认管理控制台 /user/ 接口存在
2. 前端直接 JXAjax('post', '/user/<接口名>', ...) 调用，无需改 Go 代码（genericUserProxy 已覆盖所有 /user/ POST 透传）

本地接口（仅限会话类或需多资源映射）：

1. 在 handlers.go 的 RegisterRoutes 中注册：

   mux.HandleFunc("/api/<名称>", h.<本地handler>)
   
2. 会话校验用 h.sessions.GetFromRequest(r)，转发管理控制台用 h.cloud.Post(path, body, session) 或 PostWithMainAuth
3. 编译验证：go build ./...

业务接口不要在后端新写代理路由，直接走 /user/* 透传；只有「本地会话相关」或「需要映射多资源」的接口才写专门 handler。

九、构建与验证

# 后端
go build ./...
go vet ./...

# 前端
cd front-end
npm install
npm run build      # 编译校验（有语法/引用错误会失败）

# 整体
./build.sh binary        # 仅 Go 二进制
./build.sh frontend      # 仅前端
./build.sh               # 全部

十、常见问题