From d67b765396de648f2d08d32370d5ced9b0396290 Mon Sep 17 00:00:00 2001 From: birdstorm Date: Mon, 23 Mar 2026 19:55:34 +0800 Subject: [PATCH] feat: add cocli docs --- .../cocli/4-cli-user-role-registry.md | 93 +++++++++++++++++++ .../cocli/4-cli-user-role-registry.md | 93 +++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 docs/developers/cocli/4-cli-user-role-registry.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/4-cli-user-role-registry.md diff --git a/docs/developers/cocli/4-cli-user-role-registry.md b/docs/developers/cocli/4-cli-user-role-registry.md new file mode 100644 index 00000000..bc0ccd1e --- /dev/null +++ b/docs/developers/cocli/4-cli-user-role-registry.md @@ -0,0 +1,93 @@ +--- +slug: user-role-registry +sidebar_position: 4 +--- + +# 用户、角色与容器镜像仓库 + +本节介绍与组织成员、权限角色以及刻行容器镜像仓库相关的命令。这些能力通常用于管理员或需要在本地使用 Docker 拉取/推送镜像的场景。 + +:::warning +具体标志位与输出格式请以本机 `cocli user -h`、`cocli role -h`、`cocli registry -h` 及各子命令的 `-h` 为准。 +::: + +```bash +cocli user -h +cocli role -h +cocli registry -h +``` + +## 用户 {#user} + +`cocli user` 用于查询当前登录身份所在组织（或指定项目）下的用户信息。 + +### 列举用户 {#user-list} + +- **不传 `-p`**：按**组织**范围列举用户。 +- **传入 `-p <项目 slug>`**：仅列举该项目下的用户。 +- **`--role-code`**：按角色代码过滤（例如 `PROJECT_WRITER`、`ORGANIZATION_ADMIN`）。可与 `cocli role list` 中看到的角色编码对照使用。 +- **分页**：与 `record list` 类似，使用 `--page-size`（10–100）与 `--page-token` 翻页；默认每页条数由服务端上限决定，终端会在有下一页时提示 `--page-token`。 +- **输出**：`-o` 支持 `table`、`wide`、`json`、`yaml`；`-v` 为更详细的表格列。 + +```bash +# 组织内用户 +cocli user list + +# 某项目内用户 +cocli user list -p my-project-slug + +# 按角色过滤（示例） +cocli user list --role-code PROJECT_WRITER -o json +``` + +### 查看用户详情 {#user-get} + +- **无参数**：尝试获取**当前登录用户**（若接口不可用，请显式传入用户 ID 或资源名）。 +- **有参数**：支持用户 **ID**（将解析为 `users/`）或完整资源名（如 `users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）。 + +```bash +cocli user get +cocli user get +cocli user get users/ -o json +``` + +## 角色 {#role} + +`cocli role list` 列出平台中可用的角色定义，便于与 `cocli user list --role-code` 配合使用。 + +- **`--level`**：可选 `organization` 或 `project`，只看待定层级的角色。 +- **分页**：`--page-size`、`--page-token`，行为与 `user list` 一致。 +- **输出**：`-o table|wide|json|yaml`，`-v` 更详细。 + +```bash +cocli role list +cocli role list --level project -o wide +``` + +## 容器镜像仓库 {#registry} + +`cocli registry` 用于获取刻行容器镜像仓库的临时凭证，并可选地调用本机 **Docker** 执行 `docker login`。子命令**不走与普通资源命令相同的全局登录校验**，但仍需本地配置文件中存在可用的登录配置，以便调用 OpenAPI 签发凭证。 + +### 登录 Docker（推荐） {#registry-login} + +根据当前 profile 的 **OpenAPI endpoint** 推断镜像仓库域名（例如 SaaS `openapi.coscene.cn` 对应 `cr.coscene.cn`）；若无法推断，需使用 **`--registry`** 手动指定主机名。 + +**要求**：本机已安装 Docker，且 `docker` 在 `PATH` 中。 + +```bash +cocli registry login +cocli registry login --registry cr.example.com +``` + +### 仅生成临时凭证 {#registry-create-credential} + +不调用 Docker，仅向标准输出打印用户名与密码（临时凭证）。默认纯文本两行；也可使用 `-o json` / `yaml` / `table` 便于脚本解析。 + +```bash +cocli registry create-credential +cocli registry create-credential -o json +``` + +:::tip +临时密码请视为敏感信息，勿写入版本库或日志；在 CI 中优先使用密钥管理或短期令牌策略。 +::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/4-cli-user-role-registry.md b/i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/4-cli-user-role-registry.md new file mode 100644 index 00000000..6264a39c --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/4-cli-user-role-registry.md @@ -0,0 +1,93 @@ +--- +slug: user-role-registry +sidebar_position: 4 +--- + +# Users, Roles, and Container Registry + +This page covers commands for organization members, role definitions, and the coScene container registry. They are typically used by administrators or anyone who needs to pull/push images with Docker locally. + +:::warning +For exact flags and output formats, run `cocli user -h`, `cocli role -h`, `cocli registry -h`, and `-h` on each subcommand on your machine. +::: + +```bash +cocli user -h +cocli role -h +cocli registry -h +``` + +## Users {#user} + +`cocli user` queries users in the organization (or a specific project) for the currently logged-in identity. + +### List users {#user-list} + +- **Without `-p`**: list users at the **organization** scope. +- **With `-p `**: list users in that project only. +- **`--role-code`**: filter by role code (e.g. `PROJECT_WRITER`, `ORGANIZATION_ADMIN`). Cross-check codes with `cocli role list`. +- **Pagination**: use `--page-size` (10–100) and `--page-token`, similar to `record list`; the CLI prints a suggested `--page-token` when more pages exist. +- **Output**: `-o` supports `table`, `wide`, `json`, and `yaml`; `-v` enables more columns. + +```bash +# Organization users +cocli user list + +# Users in a project +cocli user list -p my-project-slug + +# Filter by role (example) +cocli user list --role-code PROJECT_WRITER -o json +``` + +### Get user details {#user-get} + +- **No argument**: fetch the **current authenticated user** (if that fails, pass a user ID or resource name explicitly). +- **With argument**: accepts a user **ID** (resolved to `users/`) or a full resource name such as `users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. + +```bash +cocli user get +cocli user get +cocli user get users/ -o json +``` + +## Roles {#role} + +`cocli role list` lists available role definitions, useful together with `cocli user list --role-code`. + +- **`--level`**: optional `organization` or `project` to restrict the level. +- **Pagination**: `--page-size` and `--page-token`, same idea as `user list`. +- **Output**: `-o table|wide|json|yaml`, `-v` for more detail. + +```bash +cocli role list +cocli role list --level project -o wide +``` + +## Container registry {#registry} + +`cocli registry` obtains short-lived credentials for the coScene container registry and can invoke local **Docker** to run `docker login`. These subcommands use a different auth gate than most resource commands, but you still need a valid profile in your config file so the OpenAPI client can issue credentials. + +### Docker login (recommended) {#registry-login} + +The registry host is inferred from the profile **OpenAPI endpoint** (e.g. SaaS `openapi.coscene.cn` → `cr.coscene.cn`). If inference fails, pass **`--registry`** with the hostname. + +**Requires**: Docker installed and `docker` on your `PATH`. + +```bash +cocli registry login +cocli registry login --registry cr.example.com +``` + +### Print credentials only {#registry-create-credential} + +Does not call Docker; prints username and password (temporary credential) to stdout. Default is plain text; use `-o json`, `yaml`, or `table` for scripting. + +```bash +cocli registry create-credential +cocli registry create-credential -o json +``` + +:::tip +Treat temporary passwords as secrets—do not commit them or log them. In CI, prefer a secret store or short-lived tokens. +:::