SnapOtter/apps/docs/zh-TW/guide/users-roles.md

---
description: "在 SnapOtter 中管理使用者、內建與自訂角色、權限、API 金鑰、團隊、工作階段以及稽核日誌。"
i18n_source_hash: bea8955f3aff
i18n_provenance: human
i18n_output_hash: 60d6d4d6367d
i18n_hash_version: 2
---

# 使用者、角色與權限 {#users-roles-permissions}

SnapOtter 內建三種角色、17 項細緻權限，並支援具備可選之每工具存取控制的自訂角色。本頁涵蓋完整的授權模型、API 金鑰範圍限制、團隊管理以及稽核日誌。

::: tip 相關頁面
[OIDC / SSO](/zh-TW/guide/oidc) | [SAML SSO](/zh-TW/guide/saml) | [SCIM 佈建](/zh-TW/guide/scim) | [安全性與強化](/zh-TW/guide/security)
:::

## 使用者 {#users}

### 建立使用者 {#creating-users}

管理員可透過管理面板或 `POST /api/auth/register` 端點建立使用者。每位使用者都有一個使用者名稱、角色、團隊指派，以及一個選用的電子郵件地址。

### 預設管理員 {#default-admin}

首次啟動時，SnapOtter 會建立一個預設管理員帳號。憑證來自環境變數：

| Variable | Default | Description |
|---|---|---|
| `DEFAULT_USERNAME` | `admin` | 初始管理員帳號的使用者名稱 |
| `DEFAULT_PASSWORD` | `admin` | 初始管理員帳號的密碼 |

預設管理員在首次登入時必須變更密碼。

### 驗證提供者 {#authentication-providers}

使用者可透過多種方式進行驗證：

- **本機** - 使用者名稱與密碼儲存在 SnapOtter 資料庫
- **OIDC** - 任何 OpenID Connect 提供者（參閱 [OIDC / SSO](/zh-TW/guide/oidc)）
- **SAML** - SAML 2.0 身分提供者（參閱 [SAML SSO](/zh-TW/guide/saml)）
- **SCIM** - 從身分提供者自動佈建（參閱 [SCIM 佈建](/zh-TW/guide/scim)）

### 停用驗證 {#disabling-authentication}

設定 `AUTH_ENABLED=false` 以完全停用驗證。在此模式下，所有請求都會使用一個具備 `admin` 角色的合成匿名使用者。不需要登入。

::: warning 
停用驗證會授予任何能連上該執行個體的人完整的管理員存取權。僅在受信任的環境中使用。
:::

## 內建角色 {#built-in-roles}

SnapOtter 包含三種內建角色。它們無法被修改或刪除。

### Admin {#admin}

全部 17 項權限。對執行個體有完整控制權。

`tools:use` `files:own` `files:all` `apikeys:own` `apikeys:all` `pipelines:own` `pipelines:all` `settings:read` `settings:write` `users:manage` `teams:manage` `features:manage` `system:health` `audit:read` `compliance:manage` `webhooks:manage` `security:manage`

### Editor {#editor}

7 項權限。可使用所有工具並管理所有檔案與管線，但無法存取管理功能。

`tools:use` `files:own` `files:all` `apikeys:own` `pipelines:own` `pipelines:all` `settings:read`

### User {#user}

5 項權限。可使用工具並管理自己的資源。

`tools:use` `files:own` `apikeys:own` `pipelines:own` `settings:read`

## 權限參考 {#permissions-reference}

| Permission | Description |
|---|---|
| `tools:use` | 使用任何處理工具 |
| `files:own` | 檢視並管理自己的檔案 |
| `files:all` | 檢視並管理所有使用者的檔案 |
| `apikeys:own` | 建立並管理自己的 API 金鑰 |
| `apikeys:all` | 檢視所有使用者的 API 金鑰 |
| `pipelines:own` | 建立並管理自己的管線 |
| `pipelines:all` | 檢視並管理所有使用者的管線 |
| `settings:read` | 檢視執行個體設定 |
| `settings:write` | 修改執行個體設定 |
| `users:manage` | 在參與者的權限範圍內建立和管理使用者帳戶 |
| `teams:manage` | 建立、更新並刪除團隊 |
| `features:manage` | 安裝並管理 AI 功能套組 |
| `system:health` | 存取健康檢查與就緒狀態端點 |
| `audit:read` | 檢視稽核日誌並列出角色 |
| `compliance:manage` | 管理 GDPR 生命週期和合規性功能；破壞性使用者操作仍受權限限制 |
| `webhooks:manage` | 設定對外 webhook |
| `security:manage` | 管理安全性設定（IP 允許清單、SSO 強制執行） |

## 自訂角色 {#custom-roles}

具備 `security:manage` 權限的管理員可透過管理面板或角色 API 建立自訂角色。列出角色需要 `audit:read`。

### 建立自訂角色 {#creating-a-custom-role}

```bash
curl -X POST http://localhost:1349/api/v1/roles \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reviewer",
    "description": "Can use tools and view all files",
    "permissions": ["tools:use", "files:own", "files:all", "settings:read"]
  }'
```

角色名稱必須為 2 至 30 個字元，小寫英數字並可含連字號與底線。

### 委派管理邊界 {#delegated-administration-boundaries}

所有 17 個權限都可以透過自訂角色委派，但管理權限並不會使該角色等同於內建 `admin` 角色。 `users:manage`授權的使用者突變、`compliance:manage`授權的破壞性操作以及`security:manage`授權的自訂角色管理均受參與者目前權限的約束：

- 內建角色遵循`admin` > `editor` > `user`；自訂角色位於內建角色下方。
- 目標的權限必須包含在參與者的**有效**權限中。因此，限定範圍的 API 金鑰無法行使其範圍中省略的權限。
- 目標角色的工具存取權限必須包含在參與者自己的工具存取權限中。
- 當角色記錄為 `disabled:<original-role>` 時，已停用的帳戶將根據其原始角色進行檢查。
- 刪除自訂角色也需要指派內建`user`後備的權限；已停用的成員仍停用為 `disabled:user`。

全域憑證和設定更加嚴格：頒發或撤銷 SCIM 令牌以及匯入實例配置需要具有完整有效管理權限的內建 `admin` 角色。

### 工具層級權限 {#tool-level-permissions}

自訂角色可選擇性地限制使用者能存取哪些工具。有兩種模式可用：

| Mode | Behavior | License requirement |
|---|---|---|
| `category` | 依模態限制（image、video、audio、document、file） | 無（免費） |
| `tool` | 依個別工具 ID 限制 | 需要 `per_tool_permissions` 企業版功能 |

當設定了 `tool` 模式但企業版功能不可用時，SnapOtter 會優雅降級並允許存取所有工具。

```json
{
  "name": "image-only",
  "permissions": ["tools:use", "files:own"],
  "toolPermissions": {
    "mode": "category",
    "allowed": ["image"]
  }
}
```

### 刪除自訂角色 {#deleting-a-custom-role}

當自訂角色被刪除時，所有指派給它的使用者會自動重新指派到 `user` 角色。

## 團隊 {#teams}

團隊會將使用者分組，以進行儲存與保留管理。首次啟動時會建立一個 `Default` 團隊。

| Field | Type | Description |
|---|---|---|
| `name` | string | 唯一的團隊名稱（1 至 50 個字元） |
| `storageQuota` | number | 每個團隊的儲存上限（位元組）（無需企業版也可運作） |
| `retentionHours` | number | 在這麼多小時後自動刪除輸出（需要 `team_retention_overrides`，企業版） |
| `legalHold` | boolean | 防止自動刪除團隊成員的檔案（需要 `legal_hold`，企業版） |

::: info 
`Default` 團隊無法刪除。仍有成員的團隊無法刪除。請先重新指派成員。
:::

## API 金鑰 {#api-keys}

使用者可產生 API 金鑰以進行程式化存取。每把金鑰使用 `si_` 前綴，且只會在建立時顯示一次。

### 範圍限定的權限 {#scoped-permissions}

API 金鑰可選擇性地攜帶一個 `permissions` 陣列。設定後，某次請求的有效權限是使用者角色權限與金鑰範圍權限的**交集**。這表示 API 金鑰永遠無法提升到超過使用者自身的權限。

```bash
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline key",
    "permissions": ["tools:use", "files:own"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'
```

### 到期 {#expiration}

金鑰接受一個選用的 `expiresAt` 時間戳記。過期的金鑰會在驗證時被拒絕。

## 稽核日誌 {#audit-log}

SnapOtter 會在儲存於 `audit_log` 資料庫資料表的結構化稽核日誌中記錄與安全相關的事件。

### 檢視稽核日誌 {#viewing-the-audit-log}

```
GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z
```

需要 `audit:read` 權限。支援分頁（`page`、`limit`）與篩選（`action`、`ip`、`from`、`to`）。

### 工具操作稽核 {#tool-operation-auditing}

::: warning 
預設**不會**記錄 `TOOL_EXECUTED` 事件。它們需透過下列兩種途徑之一選擇加入：

1. 將 `auditToolOperations` 管理設定設為 `true`。
2. 持有具備 `audit_export` 功能的有效授權（team 與 enterprise 方案皆可使用）。

若不具備上述其一，個別的工具執行不會被記錄在稽核日誌中。
:::

### 匯出 {#exporting}

```
GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
```

需要 `audit:read` 權限與 `audit_export` 企業版功能（team 與 enterprise 方案皆可使用）。支援 CSV 與 JSON 格式，並可依 `action`、`actorId`、`targetType`、`targetId`、`from` 與 `to` 篩選。

### 防竄改簽章 {#tamper-resistant-signing}

啟用後，每筆稽核日誌項目都會以從 `DATA_ENCRYPTION_KEY` 衍生的 HMAC 簽章。這需要：

1. 在你的環境中設定 `DATA_ENCRYPTION_KEY`。
2. 啟用 `tamperResistantAudit` 管理設定。
3. 具備 `tamper_resistant_audit` 功能的企業版授權。

### 保留 {#retention}

設定 `AUDIT_RETENTION_DAYS` 以自動清除舊項目。預設值是 `0`，代表項目會無限期保留。

### 事件參考 {#event-reference}

| Event | Category |
|---|---|
| `LOGIN_SUCCESS`、`LOGIN_FAILED` | Authentication |
| `OIDC_LOGIN_SUCCESS`、`OIDC_LOGIN_FAILED` | Authentication |
| `SAML_LOGIN_SUCCESS`、`SAML_LOGIN_FAILED` | Authentication |
| `LOGOUT` | Authentication |
| `USER_CREATED`、`USER_UPDATED`、`USER_DELETED` | User management |
| `PASSWORD_CHANGED`、`PASSWORD_RESET` | User management |
| `MFA_ENROLLED`、`MFA_DISABLED`、`MFA_VERIFIED`、`MFA_VERIFY_FAILED` | MFA |
| `MFA_CHALLENGE_ISSUED`、`MFA_RECOVERY_USED`、`MFA_RESET` | MFA |
| `ROLE_CREATED`、`ROLE_UPDATED`、`ROLE_DELETED` | Roles |
| `API_KEY_CREATED`、`API_KEY_DELETED` | API keys |
| `SETTINGS_UPDATED`、`IP_ALLOWLIST_UPDATED` | Settings |
| `FILE_UPLOADED`、`FILE_DELETED` | Files |
| `TOOL_EXECUTED` | Tools (opt-in) |
| `SCIM_USER_PROVISIONED`、`SCIM_USER_UPDATED`、`SCIM_USER_DEPROVISIONED` | SCIM |
| `SCIM_GROUP_SYNCED` | SCIM |
| `LEGAL_HOLD_APPLIED`、`LEGAL_HOLD_RELEASED` | Compliance |
| `GDPR_EXPORT_INITIATED`、`GDPR_USER_PURGED`、`GDPR_TEAM_PURGED` | Compliance |
| `CONFIG_EXPORTED`、`CONFIG_IMPORTED` | Configuration |

## 工作階段管理 {#session-management}

工作階段以 cookie 為基礎，由 `SESSION_DURATION_HOURS` 控制（預設：168 小時 / 7 天）。

### 角色變更會使工作階段失效 {#role-changes-invalidate-sessions}

當管理員變更某位使用者的角色時，該使用者所有作用中的工作階段都會被刪除。使用者必須重新登入才能取得新權限。

### 安全防護 {#safety-guards}

- **最後管理員保護**：最後剩下的一位管理員無法被降級為較低角色。若你嘗試這麼做，API 會回傳錯誤。
- **防止自我刪除**：管理員無法透過 API 刪除自己的帳號。