OneAuth/scripts/tests/README.md

测试脚本说明

本目录包含 VBase 的集成测试脚本，使用 bash + curl 测试 API 功能。

⚠️ 重要注意事项 (必读)

1. 环境重置与管理员权限：

   • 系统设计为：数据库重置后第一个注册的用户自动获得 Admin (超级管理员) 权限。
   • 后续注册的用户默认为普通 User 权限。
   • 很多权限测试（如 02_resource_perm.sh）依赖于这个机制。如果数据库未清理，新注册的用户可能只是普通用户，导致 Admin 权限测试失败。
   • 强烈建议使用 clean_run.sh 脚本运行测试。该脚本会自动清理数据库 (/tmp/vb.sqlite) 并重启服务，确保环境一致性。

2. BASE_URL 配置：

   • 测试脚本依赖 BASE_URL 环境变量连接服务。
   • 如果你的系统环境变量中设置了其他的 BASE_URL（例如生产环境地址），直接运行脚本可能会导致连接错误或误操作。
   • clean_run.sh 会强制设置 BASE_URL=http://localhost:4000，确保测试在本地隔离环境中运行。

目录结构

scripts/tests/
├── README.md                 # 本说明文件
├── lib.sh                    # 公共函数库
├── clean_run.sh              # [推荐] 一键清理环境、重启服务并运行所有测试
├── run_all.sh                # 运行所有测试脚本 (不负责清理环境)
├── 00_none_auth.sh           # 1. 未登录访问测试
├── 01_setup_users.sh         # 2. 用户初始化与基础认证
├── 02_resource_perm.sh       # 3. 资源权限交叉测试
├── 03_org_permission.sh      # 4. 组织权限测试
└── 04_org_load_middleware.sh # 5. LoadOrg 中间件测试

推荐运行方式

方式一：一键清理并运行 (强烈推荐)

最稳健的测试方式，自动处理数据库清理、服务重启和环境变量配置：

# 在项目根目录下或 scripts/tests 目录下运行
bash scripts/tests/clean_run.sh

方式二：手动运行

如果你需要手动运行单个脚本进行调试，请确保：

1. 服务已启动 (go run cli/main.go ...)。
2. BASE_URL 指向正确的本地服务。
3. 如果测试依赖 Admin 权限，请确保你使用的 Token 属于 Admin 用户。

# 1. 设置环境变量
export BASE_URL=http://localhost:4000
export TEST_TIMESTAMP=$(date +%s) # 生成统一时间戳，避免数据冲突

# 2. 运行特定测试
bash scripts/tests/02_resource_perm.sh

测试脚本详情

00_none_auth.sh

测试内容：未登录状态下访问受保护接口

• 验证 API 是否正确拦截未携带 Token 的请求
• 覆盖 Users, Orgs, Roles, Settings 等核心模块

01_setup_users.sh

测试内容：用户初始化与基础功能验证

• 注册三个核心账户：Admin, User1, User2
• 验证注册与登录流程
• 验证基础功能：修改个人信息、修改密码、Token 刷新、用户登出

02_resource_perm.sh

测试内容：跨用户资源访问权限验证

• 场景 1: Admin 修改任意用户信息 (允许)
• 场景 2: User1 修改自己信息 (允许)
• 场景 3: User1 修改 User2 信息 (禁止 403)
• 场景 4: User1 修改 Admin 信息 (禁止 403)
• 场景 5: User2 修改 User1 信息 (禁止 403)

03_org_permission.sh

测试内容：组织权限控制

• admin 创建组织
• user 不能修改他人创建的组织
• admin 邀请 user 加入组织
• 普通成员不能修改组织信息
• 只有 admin/owner 可以修改组织

04_org_load_middleware.sh

测试内容：LoadOrg 中间件验证

• 验证 X-Org-ID 头部的处理
• 验证用户是否为组织成员的检查逻辑
• 验证非成员访问组织资源被拒绝 (403)
• 验证成员访问组织资源被允许 (200)

测试环境变量参考

变量	默认值	说明
BASE_URL	http://localhost:4000	测试服务的 API 地址
TEST_TIMESTAMP	date +%s	测试运行的时间戳，用于生成唯一的用户名/邮箱

常见问题与踩坑记录 (Troubleshooting)

1. 权限测试失败：Admin 用户无法修改他人信息

现象： 运行 02_resource_perm.sh 时，提示 Admin 修改 User1 失败 或返回 403。

原因： VBase 的逻辑是系统初始化的第一个用户自动获得 Admin 权限。如果你在测试前没有清理数据库，数据库中可能已经存在其他用户，导致你测试脚本中注册的 "Admin" 用户实际上只获得了普通 User 权限。

解决： 使用 clean_run.sh 运行测试，或者手动删除数据库文件 /tmp/vb.sqlite 后重启服务。

2. 连接被拒绝 (Connection refused) 或 404

现象： 测试脚本提示无法连接到服务器，或者返回非预期的 404。

原因：

• 服务未启动。
• BASE_URL 环境变量配置错误（例如系统环境中设置了生产环境地址）。

解决：

• 确保服务正在运行且监听端口与 BASE_URL 一致（默认 4000）。
• 强制指定 BASE_URL：export BASE_URL=http://localhost:4000。

3. 端口被占用 (Address already in use)

现象： 运行 go run cli/main.go ... 时提示端口 4000 被占用。

原因： 之前的测试服务没有正常关闭，或者有其他服务占用了该端口。

解决： 查找并关闭占用端口的进程：

lsof -i :4000
kill -9 <PID>

clean_run.sh 脚本已内置了此清理逻辑。

4. 数据不一致 / 用户不存在

现象： 手动运行多个脚本时，提示用户不存在或登录失败。

原因： 测试脚本使用 TEST_TIMESTAMP 生成唯一的用户名（如 user1_1712345678）。如果你分别运行两个脚本且没有固定 TEST_TIMESTAMP，第二个脚本会生成新的时间戳，导致无法找到第一个脚本创建的用户。

解决： 在手动运行一系列脚本前，先导出时间戳：

export TEST_TIMESTAMP=$(date +%s)
bash 01_setup_users.sh
bash 02_resource_perm.sh