---
title: 身份验证
description: "登录、管理会话并了解 Jamdesk CLI 如何进行身份验证，涵盖令牌存储、会话刷新、团队账户和 CI/CD 环境。"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

CLI 使用基于浏览器的身份验证来连接您的 Jamdesk 账户。部署前需要先登录。

## 登录

```bash
jamdesk login
```

此命令会在浏览器中打开 Jamdesk 仪表板进行身份验证。其工作流程如下：

1. CLI 在 `127.0.0.1:9876` 上启动本地 HTTP 服务器（如果 9876 端口繁忙，则回退到操作系统分配的端口）
2. 浏览器打开 `dashboard.jamdesk.com/cli-auth`
3. 您使用任意仪表板登录方式进行身份验证（电子邮件/密码、Google、GitHub）
4. 仪表板将您的凭据发送回 CLI 的本地服务器
5. 凭据存储在 `~/.jamdeskrc` 中

回调时会验证状态参数，以防止跨站请求伪造。登录流程会在 2 分钟后超时。

```bash Expected output
$ jamdesk login
ℹ Open this URL in your browser to log in:

  https://dashboard.jamdesk.com/cli-auth?port=9876&state=abc123...

ℹ Waiting for authentication...
✔ Logged in as you@example.com
```

**无头环境和 SSH 环境**：即使无法打开浏览器，终端也始终会打印 URL。将其复制并粘贴到任意浏览器中。

## 登出

```bash
jamdesk logout
```

清除 `~/.jamdeskrc` 中存储的凭据。如果您未登录，则不会执行任何操作。

```bash Expected output
$ jamdesk logout
✔ Logged out (you@example.com)
```

## Whoami

```bash
jamdesk whoami
```

显示您的已验证电子邮件地址，并通过刷新令牌验证会话。这是实时检查，而不是读取本地缓存。

共有三种可能的状态：

<CodeGroup>
```bash Logged in
$ jamdesk whoami
✔ Logged in as you@example.com
```

```bash Session expired
$ jamdesk whoami
⚠ Logged in as you@example.com (session expired)
  Run `jamdesk login` to re-authenticate.
```

```bash Not logged in
$ jamdesk whoami
ℹ Not logged in. Run `jamdesk login` to authenticate.
```
</CodeGroup>

## 会话工作原理

凭据以 JSON 格式存储在 `~/.jamdeskrc` 中，并具有 `0600` 权限（仅所有者可读写）：

```json ~/.jamdeskrc
{
  "auth": {
    "refreshToken": "AGK...",
    "email": "you@example.com",
    "uid": "abc123",
    "expiresAt": 1700000000000
  }
}
```

CLI 使用**刷新令牌 + ID 令牌**架构：

- **ID 令牌**约 1 小时后过期，用于 API 调用
- CLI 会使用存储的刷新令牌**自动刷新** ID 令牌，并在过期前 5 分钟进行刷新
- 刷新令牌的有效期较长，但可能会被撤销（例如密码更改、账户删除）
- 如果刷新令牌永久失效（`TOKEN_EXPIRED`、`USER_NOT_FOUND`、`INVALID_REFRESH_TOKEN`），系统会自动清除存储的身份验证信息

您无需手动管理令牌。CLI 会在每个需要身份验证的命令中透明地处理刷新操作。

## 故障排除

<AccordionGroup>
  <Accordion title="登录在 2 分钟后超时">
    CLI 的本地回调服务器可能被防火墙阻止。复制打印出的 URL，并在浏览器中手动打开。

    如果端口 9876 已被其他进程占用，CLI 会自动选择其他端口。请检查终端输出中的 URL。
  </Accordion>

  <Accordion title='"每个命令都显示“会话已过期”"'>
    您的刷新令牌已不再有效。密码更改或长时间不活动后可能会发生这种情况。

    运行 `jamdesk login` 以获取新会话。
  </Accordion>

  <Accordion title="浏览器未打开">
    这在无头环境（SSH、Docker、CI）中是预期行为。从终端复制 URL，并在能够访问您计算机回调端口的任意浏览器中打开。
  </Accordion>

  <Accordion title='"登录后立即显示“未登录”"'>
    检查 `~/.jamdeskrc` 是否存在并包含 `auth` 键：

    ```bash
    cat ~/.jamdeskrc
    ```

    文件权限应为 `0600`。如果文件缺失，您的主目录可能存在权限问题；使用 `ls -la ~` 检查。
  </Accordion>
</AccordionGroup>

如需了解更多 CLI 故障排除信息，请参阅[帮助中心 CLI 指南](/cn/help/troubleshooting/cli-issues)。

## 接下来？

<Columns cols={2}>
  <Card title="CLI 部署" icon="cloud-arrow-up" href="/cn/cli/deploy">
    从终端部署您的文档
  </Card>
  <Card title="CLI 概览" icon="terminal" href="/cn/cli/overview">
    一览所有 CLI 命令
  </Card>
</Columns>