5.5 KiB

Raw Permalink Blame History

gitlink-org 参考手册

本文档定义组织管理的 API 字段映射、权限模型、批量邀请细节和治理审计标准。

一、组织 API 字段映射

org +list 关键字段

{
  "id": 152434,
  "name": "algo",
  "nickname": "algo",
  "description": "组织描述",
  "created_at": "2026-06-12",
  "num_projects": 1,
  "num_teams": 1,
  "num_users": 3,
  "visibility": "common",
  "pms_enable": false,
  "website": null,
  "location": null,
  "max_repo_creation": -1
}

字段	类型	用途
`id`	int	组织数字 ID（Raw API 需要）
`name`	string	组织标识/login name（sc 命令的 `--id` 参数）
`nickname`	string	显示名称，可能与 name 不同
`num_projects`	int	组织下项目总数
`num_teams`	int	团队数量
`num_users`	int	成员总数
`visibility`	string	`common` = 公开
`created_at`	date	创建日期
`pms_enable`	bool	是否开启项目管理（PM）
`max_repo_creation`	int	最大可创建仓库数（-1 = 无限制）

org +info 关键字段

在 org +list 基础上增加：

{
  "can_create_project": false,
  "is_admin": false,
  "is_member": false,
  "enabling_cla": false,
  "repo_admin_change_team_access": false,
  "memo": null,
  "news_banner_id": null,
  "news_content": null,
  "news_title": null,
  "news_url": null
}

字段	用途
`is_admin`	关键：当前用户是否为管理员（决定能否写入）
`is_member`	当前用户是否为成员
`can_create_project`	当前用户能否在组织中创建项目
`enabling_cla`	是否启用 CLA（贡献者许可协议）
`repo_admin_change_team_access`	仓库管理员能否修改团队访问权限

org +members 关键字段

{
  "id": 28300,
  "created_at": "2026-06-12",
  "team_names": ["Owner团队"],
  "user": {
    "user_id": 28300,
    "login": "gluo",
    "name": "Guojie Luo",
    "mail": "gluo@pku.edu.cn",
    "identity": "副教授",
    "image_url": "images/avatars/User/28300?t=1680871392",
    "watched": false
  }
}

字段	用途
`id`	组织用户关联 ID（`organization_user_id`），移除成员时需要
`created_at`	加入组织时间
`team_names`	所属团队列表，空数组 = 未分配
`user.login`	用户名（login），用于 `--users` 参数
`user.user_id`	用户数字 ID
`user.mail`	邮箱，辅助判断成员所属机构
`user.identity`	身份标签：副教授/专业人士/学生/...

二、权限模型

组织角色

角色	权限
Owner（创建者）	完全控制：删除组织、管理成员、创建团队
Admin（管理员）	管理成员、创建团队、创建项目
Member（成员）	创建项目、参与团队
非成员	仅查看公开信息

权限检查流程

1. org +info --id <org> → 检查 is_admin
2. if is_admin == false:
   - 写入操作不可用
   - 向用户说明需要管理员权限
3. if is_admin == true:
   - 可执行写入操作

三、批量邀请详解

org +batch-invite 参数

参数	必填	说明
`--id, -i`	是	组织 login name（不是数字 ID）
`--users, -u`	是*	逗号分隔的用户名或用户 ID
`--from`	是*	CSV 文件路径
`--role, -r`	否	`member`（默认）或 `admin`
`--dry-run`	否	预览模式

用户名格式

支持两种格式：
1. login 名: alice, bob → CLI 自动解析为数字 user_id
2. 数字 ID: 28300, 152435 → 直接使用

CSV 格式

user
alice
bob
charlie

支持的列名：user / login / user_id。无表头时默认首列为用户名。

邀请流程

1. org +info --id <org> → 确认 is_admin
2. org +batch-invite --dry-run → 预览
3. 展示邀请列表 → 用户确认
4. org +batch-invite 执行
5. org +members --id <org> → 验证

四、团队管理 API

通过 Raw API 操作团队：

# 获取团队列表
GET /organizations/<org-name>/teams

# 创建团队
POST /organizations/<org-name>/teams
Body: {"name": "dev-team", "description": "开发团队"}

# 获取团队详情
GET /organizations/<org-name>/teams/<team-id>

# 更新团队
PUT /organizations/<org-name>/teams/<team-id>
Body: {"name": "new-name"}

# 删除团队
DELETE /organizations/<org-name>/teams/<team-id>

五、已知限制

限制	说明
`api POST` bug	`api` 子命令有 URL 拼接 bug，团队创建等操作可能需网页完成
组织名称不可改	`org +create` 后 name 永久固定
成员移除需 ID	移除成员需要 `organization_user.id`（不是 `user.user_id`）
无批量移除	没有 `batch-remove` 命令，需逐个通过 Raw API 操作

六、常见问题

A: 使用 login name（如 algo），不是数字 ID（如 152434）。org +list 返回的 name 字段即为 login name。

Q: 如何判断用户是否有管理权限？

A: 检查 org +info 返回的 is_admin 字段。true = 可管理成员。

Q: 批量邀请失败怎么排查？

A: 1) 确认 is_admin = true；2) 确认用户名存在（可通过 search +users 验证）；3) 确认用户未被邀请过。

Q: 如何移除不活跃成员？

A: 先通过 org +members 获取成员的 id（organization_user_id），然后 api DELETE /organizations/<org>/organization_users/<id>。

5.5 KiB Raw Permalink Blame History Unescape Escape