> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub2api.ruilinlu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux 上使用 Sub2API 的完整指南

> 在 Linux 服务器或桌面上配置 Sub2API 环境变量并进行验证性 API 调用。

本教程适用于 Ubuntu、CentOS、Debian 等常见 Linux 发行版，介绍如何安装 Python 与 pip、配置环境变量并在终端完成第一次 Sub2API 调用。

<Steps>
  <Step title="安装 Python 与 pip">
    根据你的发行版选择对应的包管理器命令：

    <CodeGroup>
      ```bash Debian/Ubuntu theme={null}
      sudo apt update
      sudo apt install -y python3 python3-pip
      ```

      ```bash CentOS/RHEL (yum) theme={null}
      sudo yum install -y python3 python3-pip
      ```

      ```bash Fedora (dnf) theme={null}
      sudo dnf install -y python3 python3-pip
      ```
    </CodeGroup>

    安装完成后验证：

    ```bash theme={null}
    python3 --version
    pip3 --version
    ```
  </Step>

  <Step title="设置环境变量">
    编辑 `~/.bashrc`（或你使用的 Shell 配置文件）：

    ```bash theme={null}
    export OPENAI_API_KEY="YOUR_API_KEY"
    export OPENAI_BASE_URL="https://sub2api.ruilinlu.com"
    ```

    保存后加载配置：

    ```bash theme={null}
    source ~/.bashrc
    ```

    用以下命令确认：

    ```bash theme={null}
    echo $OPENAI_API_KEY
    echo $OPENAI_BASE_URL
    ```
  </Step>

  <Step title="安装 openai SDK">
    ```bash theme={null}
    pip3 install openai
    ```

    若提示权限不足，建议添加 `--user` 参数，或使用虚拟环境：

    ```bash theme={null}
    python3 -m venv venv
    source venv/bin/activate
    pip install openai
    ```
  </Step>

  <Step title="测试调用">
    创建 `test.py`：

    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.getenv("OPENAI_API_KEY"),
        base_url=os.getenv("OPENAI_BASE_URL")
    )

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello from Linux!"}]
    )

    print(response.choices[0].message.content)
    ```

    执行：

    ```bash theme={null}
    python3 test.py
    ```
  </Step>
</Steps>

## 为 systemd 服务配置环境变量

若你的应用程序以 systemd 服务运行，推荐在服务单元文件中显式声明环境变量：

```ini theme={null}
[Service]
Environment="OPENAI_API_KEY=YOUR_API_KEY"
Environment="OPENAI_BASE_URL=https://sub2api.ruilinlu.com"
ExecStart=/usr/bin/python3 /opt/app/main.py
```

修改后执行 `sudo systemctl daemon-reload` 并重启服务。

## 常见问题排查

<Accordion title="apt/yum 找不到 python3 包">
  某些精简系统可能未启用默认软件源。请先执行 `sudo apt update` 或检查 `/etc/apt/sources.list` 配置。
</Accordion>

<Accordion title="pip3 install 速度很慢">
  可更换国内镜像源加速安装：

  ```bash theme={null}
  pip3 install openai -i https://pypi.tuna.tsinghua.edu.cn/simple
  ```
</Accordion>

<Accordion title="调用返回 403 Forbidden">
  Sub2API 明确不支持中国大陆地区访问。若服务器位于 mainland China，请更换至支持的区域部署。详情见 [支持区域政策](/policies/supported-regions)。
</Accordion>

<Accordion title="systemd 服务中环境变量不生效">
  请确认环境变量写在 `[Service]` 段落下，而非 `[Unit]` 或 `[Install]`。修改后务必执行 `daemon-reload`。
</Accordion>