AIstudioProxyAPI 安装指南

在 Ubuntu 22.04 从零安装 AIstudioProxyAPI v4.1.2_py：Python+Poetry 直跑与 Docker Compose 两种形态，含 Camoufox 浏览器、系统依赖、认证登录与 8 类排障实录。

AIstudioProxyAPIAIstudioProxyAPILLM2026/10/23

AIstudioProxyAPI 安装指南

目标：在 Ubuntu 22.04 服务器上从零完成 AIstudioProxyAPI（v4.1.2_py）的安装与启动验证，覆盖 Python + Poetry 直接运行（含 Camoufox 无头浏览器）与 Docker Compose 两种官方部署形态，以及系统依赖、配置、systemd 托管与常见故障排除。已在 Ubuntu 22.04 环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Python：3.10.12（项目要求 ≥3.9 且 <4.0，推荐 3.10+/3.11+）
  • Poetry：2.5.1（依赖管理工具，官方指定）
  • Git：2.34.1
  • AIstudioProxyAPI：v4.1.2_py（2026-04-18 发布，官方最新稳定版，查询日期 2026-10-23）
  • Camoufox：随 Python 包安装，浏览器本体经 camoufox fetch 下载（实测约 2.4GB）
  • 主 API 端口：2048（默认）；流式代理端口：3120（默认，可关闭）
  • 项目目录：/opt/AIstudioProxyAPI
  • 认证文件目录：/opt/AIstudioProxyAPI/auth_profiles/（active/saved/emergency 三级）

二、前置条件

2.1 硬件与系统要求

官方要求的最低配置如下（来源：官方仓库 README，查询日期 2026-10-23）：

组件要求推荐
Python>=3.9, <4.03.10+ / 3.11+
依赖管理Poetry最新版本
Node.js前端构建需要LTS
内存>=2GB>=4GB

⚠️ 注意：本项目运行时需拉起完整的 Firefox 定制浏览器（Camoufox）实例，内存 2GB 是下限，生产建议 4GB 以上；Node.js 仅在需要本地构建内置 Web UI 前端时使用，直接使用仓库内预置静态资源时可不装。

2.2 网络要求

  • 需要访问 GitHub（拉取仓库与依赖包）、Camoufox 资源服务器（下载浏览器与模型文件）、Google（AI Studio 网页）；中国大陆服务器需自备可访问上述站点的 HTTP 代理，并通过 UNIFIED_PROXY_CONFIG 注入；
  • 本指南实验环境的代理出口为 http://192.168.1.62:7897，后文命令中的该地址请按你的实际代理地址替换。

2.3 基础工具安装

安装 Python、pip、git、curl 等基础工具：

apt-get update
apt-get install -y python3 python3-pip python3-venv git curl

实测回显（版本确认）：

python3 --version

Python 3.10.12

pip3 --version

pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

git --version

git version 2.34.1

三、版本选型说明

版本取证（查询日期 2026-10-23，官方仓库 Releases）：

版本状态说明
v4.1.2_py最新稳定版（本指南采用）修复 AI Studio UI 遮罩卡死问题（PR #316），发布于 2026-04-18
v4.1.1_py / v4.1.0_py上一批稳定版新增多实例 Docker 管理器、文档重构
v4.0.x_py旧稳定线大规模架构重构（模块化 v2、严格类型标注）
Nightly Build预发布（main 分支每日构建）含未测试改动，不建议生产使用

⚠️ 注意：版本 tag 带 _py 后缀（Python 实现线），拉取时务必 checkout 到 _py 后缀的最新 tag；Nightly 是自动化构建，包含未经充分验证的变更。

选型建议：生产环境使用 v4.1.2_py；追新可测 Nightly；升级前先看 Releases 是否包含「AI Studio 选择器更新」类修复——该项目对上游网页改版的响应较快，长期不升级反而更容易因网页改版而不可用。

四、安装方案 A：Python + Poetry 直接运行（推荐）

本方案为官方推荐的调试与灵活控制形态：Poetry 管理依赖，launch_camoufox.py 统一拉起 Camoufox 浏览器与 FastAPI 服务。以下为从零到一的完整过程，全部命令与回显均在 Ubuntu 22.04 实测。

4.1 安装 Poetry

pip3 install poetry

实测输出节选（实测首尾）：

Collecting poetry
  Downloading poetry-2.5.1-py3-none-any.whl (285 kB)
  ...（中间依赖安装省略）...
Successfully installed build-1.4.0 cachecontrol-0.14.0 ... poetry-2.5.1 ...
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

⚠️ 注意：以 root 运行 pip 会出现上述 WARNING，属正常提醒；如需规避可创建专用普通用户操作。验证安装：

poetry --version

Poetry (version 2.5.1)

4.2 获取源码并切换到稳定版本

cd /opt
git clone https://github.com/CJackHwang/AIstudioProxyAPI.git
cd AIstudioProxyAPI
git checkout v4.1.2_py

实测确认版本与 tag 列表（输出节选）：

git tag | tail -8

v4.0.2_py
v4.0.3_py
v4.0.4_py
v4.0.5_py
v4.0.6_py
v4.1.0_py
v4.1.1_py
v4.1.2_py

git log -1 --format='%h %cd' --date=iso

fd1da7b 2026-04-18 07:57:36 +0800

4.3 安装 Python 依赖

poetry install

实测输出节选（实测首尾）：

Creating virtualenv aistudioproxyapi in /root/.cache/pypoetry/virtualenvs
Updating dependencies
Resolving dependencies... (1.3s)
Package operations: 63 installs, 0 updates, 0 removals
  - Installing fastapi (0.129.0)
  ...（中间依赖安装省略）...
  - Installing uvicorn (0.29.0)
  - Installing uvloop (0.22.1)
  - Installing websockets (12.0)
  - Installing werkzeug (3.1.3)
  - Installing yarl (1.22.0)

验证核心依赖可用：

poetry run python -c 'import fastapi, playwright; print("deps ok")'

deps ok

4.4 安装 Camoufox 浏览器与模型文件

Camoufox 的 Python 包装安装后，浏览器本体与指纹模型文件需单独拉取。首次运行 launch_camoufox.py 时会自动下载模型定义文件，浏览器本体需执行 camoufox fetch 安装。

拉取模型定义文件（首次运行 --help 即会触发）：

poetry run python launch_camoufox.py --help

⚠️ 排障实录：不带代理直连时，模型定义文件下载会失败并中断启动，实测报错如下（逐行照抄）：

Downloading model definition files...
Error downloading fingerprint-network.zip: Remote end closed connection without response
Error downloading input-network.zip: <urlopen error [Errno 111] Connection refused>
Traceback (most recent call last):
  File "/opt/AIstudioProxyAPI/launch_camoufox.py", line 40, in <module>
    import camoufox.server
  ...
FileNotFoundError: [Errno 2] No such file or directory: '/root/.cache/pypoetry/virtualenvs/aistudioproxyapi-cKjAx_aG-py3.10/lib/python3.10/site-packages/browserforge/headers/data/input-network.zip'

解决：让下载流量走 HTTP 代理后重跑（urllib 会读取 http_proxy/https_proxy 环境变量）：

export http_proxy=http://192.168.1.62:7897
export https_proxy=http://192.168.1.62:7897
poetry run python launch_camoufox.py --help

走代理后的成功回显（模型文件下载 + 帮助输出首部，实测照抄）：

Downloading model definition files...
header-network.zip            OK!
browser-helper-file.json      OK!
input-network.zip             OK!
headers-order.json            OK!
fingerprint-network.zip       OK!
2026-10-22 22:26:16,596 - INFO - ============================== Camoufox Launcher Logging Initialized ==============================
2026-10-22 22:26:16,596 - INFO - Log level set to: INFO
2026-10-22 22:26:16,596 - INFO - Log file path: /opt/AIstudioProxyAPI/logs/launch_app.log
usage: launch_camoufox.py [-h] [--server-port SERVER_PORT]
                          [--stream-port STREAM_PORT] [--helper HELPER]
                          [--camoufox-debug-port CAMOUFOX_DEBUG_PORT]
                          [--debug | --headless | --virtual-display]
                          ...

下载浏览器本体（实测约 2.4GB，耗时视带宽而定）：

export http_proxy=http://192.168.1.62:7897
export https_proxy=http://192.168.1.62:7897
poetry run camoufox fetch

验证浏览器本体就位：

ls /root/.cache/camoufox/ | head -6

addons
application.ini
browser
camoufox
camoufox-bin
camoufox.cfg

⚠️ 排障实录：跳过 camoufox fetch 直接启动 headless 模式时，会得到如下报错（实测照抄）：

FileNotFoundError: Version information not found at /root/.cache/camoufox/version.json. Please run `camoufox fetch` to install.

按提示执行 poetry run camoufox fetch 即可解决。

4.5 安装浏览器运行所需系统库

Camoufox 是 Firefox 定制版，依赖 GTK3 等 GUI 系统库。官方 Dockerfile 中给出了完整依赖清单，最小化安装的服务器（无桌面环境）需要先补齐：

apt-get install -y --no-install-recommends \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 \
  libgtk-3-0 libnspr4 libnss3 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
  libxdamage1 libxext6 libxfixes3 libxrandr2 libxrender1 libxtst6 \
  ca-certificates fonts-liberation libasound2 libpangocairo-1.0-0 \
  libpango-1.0-0 libu2f-udev

实测输出节选（实测首尾）：

Setting up ubuntu-mono (20.10-0ubuntu2) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

⚠️ 排障实录：缺这批库时浏览器进程会启动失败，实测报错关键行（逐行照抄）：

[pid=4419][err] XPCOMGlueLoad error for file /root/.cache/camoufox/libmozgtk.so:
[pid=4419][err] libgtk-3.so.0: cannot open shared object file: No such file or directory
[pid=4419][err] Couldn't load XPCOM.
❌ Error (--internal-launch-mode): Exception executing camoufox.server.launch_server: Server process terminated unexpectedly
RuntimeError: Server process terminated unexpectedly

补装上述系统库后重试即可。另外若在无 user namespace 的受限环境看到 Sandbox: CanCreateUserNamespace() clone() failure: EPERM，Firefox 会自动降级沙箱策略，不阻断启动。

4.6 初始化配置

cp .env.example .env

首次启动前建议确认 .env 中以下五项（官方 README 建议项，完整参数见《AIstudioProxyAPI 配置参数详解》）：

grep -E '^(PORT|STREAM_PORT|UNIFIED_PROXY_CONFIG|LAUNCH_MODE|FUNCTION_CALLING_MODE)=' .env

PORT=2048
STREAM_PORT=3120
UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
LAUNCH_MODE=normal
FUNCTION_CALLING_MODE=auto
  • PORT：主 API 端口，默认 2048；
  • STREAM_PORT：流式代理端口，设为 0 可关闭；
  • UNIFIED_PROXY_CONFIG：统一代理（访问 Google 与浏览器流量都走它），按你的实际代理地址修改；服务器可直连 Google 时留空；
  • LAUNCH_MODE：启动模式（normal/debug/headless/virtual_display/direct_debug_no_browser），命令行参数会覆盖该值；
  • FUNCTION_CALLING_MODE：函数调用模式（auto/native/emulated），默认 auto。

4.7 首次启动：交互式登录并保存认证

首次启动必须使用 --debug 模式（浏览器窗口可见，人工登录 Google 账号）。Linux 服务器无图形界面时，先在桌面环境完成登录保存认证文件，或使用带虚拟显示的方式（见 4.8）：

cd /opt/AIstudioProxyAPI
poetry run python launch_camoufox.py --debug --auto-save-auth --save-auth-as myaccount
  • --auto-save-auth：登录成功后自动提示保存认证状态；
  • --save-auth-as myaccount：认证文件保存名为 myaccount.json；
  • --exit-on-auth-save：可追加该参数，保存认证后自动退出启动器。

登录成功并保存认证后，把认证文件放入 active 目录（保存的文件默认位于 auth_profiles/saved/，将其复制或移动到 auth_profiles/active/ 供 headless 使用）：

cp auth_profiles/saved/myaccount.json auth_profiles/active/

⚠️ 注意：本项目需要你自备 Google 账号并完成 AI Studio 登录；没有有效认证文件时，headless 模式会拒绝启动（见 4.8 排障实录）。本指南实验环境无法登录 Google 账号，认证环节的实测以「无认证文件/无效认证文件的报错回显」为准，成功登录后的界面操作请按启动器内提示进行。

4.8 日常启动：headless 无头模式

有认证文件后，用 headless 模式常驻运行：

poetry run python launch_camoufox.py --headless --server-port 2048 --stream-port 0

实测启动链路日志（输出节选，实测首尾）：

2026-10-22 22:33:52,078 - INFO - 🚀 Camoufox Launcher Started 🚀
2026-10-22 22:33:52,078 - INFO - --- Step 1: Check Dependencies ---
2026-10-22 22:33:52,078 - INFO -   ✓ Module 'camoufox' found.
2026-10-22 22:33:52,078 - INFO -   ✓ Successfully imported 'app' object from 'server.py'.
2026-10-22 22:33:52,078 - INFO - ✅ All launcher dependency checks passed.
2026-10-22 22:33:52,078 - INFO - --- Step 2: Check if FastAPI server target port (2048) is in use ---
2026-10-22 22:33:52,079 - INFO -   ✅ Port 2048 (host 0.0.0.0) is currently available.
2026-10-22 22:33:52,079 - INFO - --- Step 3: Prepare and start Camoufox internal process ---
2026-10-22 22:33:53,505 - INFO - [InternalCamoufox-stdout-PID:5515]: Websocket endpoint: ws://localhost:9222/a67c8aa54bf2c9a646304bb3b78cb917
2026-10-22 22:33:53,505 - INFO -   ✅ Successfully captured WebSocket endpoint from Camoufox internal process: ws://localhost:9222/a67c8aa54bf2c9a64630...
2026-10-22 22:33:55,506 - INFO - --- Step 5: Start Integrated FastAPI Server (Listening on: 2048) ---
22:33:55.536 INF SYS           Starting AI Studio Proxy Server...
22:33:55.713 INF SYS           Connecting to browser at: ws://localhost:9222/a67c8aa54bf2c9a646304bb3b78cb917
22:33:55.744 INF SYS           [Navigation] Opening new page: https://aistudio.google.com/prompts/new_chat
22:33:58.442 ERR SYS           Detected redirect to login page in headless mode, authentication may have expired. Please update the auth file.
22:33:58.451 CRT SYS           Application startup failed: Unexpected page initialization error: Auth failed in headless mode, auth file update required.

启动链路说明：Step 1 依赖检查 → Step 2 端口占用检查 → Step 3 拉起 Camoufox 内部进程并捕获 WebSocket Endpoint（ws://localhost:9222/…）→ Step 4 注入 CAMOUFOX_WS_ENDPOINT 等环境变量 → Step 5 启动 FastAPI（监听 2048）并由 Playwright 连接浏览器打开 AI Studio 页面；认证校验通过后服务进入可用状态。实测环境因无有效 Google 认证，止步于 Auth failed in headless mode——这正是「认证文件无效/过期」时的标准报错，说明链路中浏览器、导航与登录检测均工作正常。

⚠️ 排障实录 1：auth_profiles/active/ 目录为空时，headless 启动直接失败（实测照抄）：

ERROR -   ❌ headless Mode Error: No active profile found in '/opt/AIstudioProxyAPI/auth_profiles/active' and AUTO_AUTH_ROTATION_ON_STARTUP is disabled.
ERROR -      Please ensure a profile exists in '/opt/AIstudioProxyAPI/auth_profiles/active' or enable auto-rotation.

解决：先按 4.7 完成 --debug 登录并保存认证，再把认证 JSON 放入 auth_profiles/active/；或启动时加 --auto-auth-rotation-on-startup true 让启动器自动从 saved/emergency 池选取。

⚠️ 排障实录 2：不要用 python server.py 直接启动（除非已另行运行 Camoufox 并配置 CAMOUFOX_WS_ENDPOINT）。实测直接运行 poetry run python server.py 的报错（逐行照抄）：

22:26:23.241 CRT SYS           Application startup failed: CAMOUFOX_WS_ENDPOINT environment variable is missing.
ValueError: CAMOUFOX_WS_ENDPOINT environment variable is missing.

server.py 只是 FastAPI 服务本体，浏览器连接端点由 launch_camoufox.py 拉起浏览器后注入。日常一律用 launch_camoufox.py 启动。

4.9 验证服务

服务完整启动（认证校验通过）后，用健康检查与模型列表接口验证：

curl http://127.0.0.1:2048/health
curl http://127.0.0.1:2048/v1/models

/health 返回 200 表示核心状态正常，返回 503 时请关注响应体 details 字段中的 browser/page/worker 状态（来源：官方 api-usage 文档）。浏览器访问 http://127.0.0.1:2048/ 进入内置 Web UI 管理面板，可查看日志与状态。

💡 说明：API 调用实测依赖有效 Google 认证，本指南实验环境无法登录 Google，故接口级验证以官方文档口径与启动日志为准；认证就绪后上述命令即为完整验证路径。API 端点的参数与响应结构详见《AIstudioProxyAPI 常用 CLI 命令与工具详解》。

4.10 systemd 托管（服务器常驻）

创建 /etc/systemd/system/aistudio-proxy.service（示例与官方 deployment-and-operations 文档一致）：

[Unit]
Description=AI Studio Proxy API
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/AIstudioProxyAPI
ExecStart=/usr/bin/env poetry run python launch_camoufox.py --headless
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

逐项说明：WorkingDirectory 必须指向项目目录（.env 与 auth_profiles 按相对路径读取）；ExecStart 以 headless 模式常驻；Restart=always 保证进程异常退出后自动拉起。

启用并启动：

systemctl daemon-reload
systemctl enable aistudio-proxy
systemctl start aistudio-proxy
systemctl status aistudio-proxy --no-pager

⚠️ 注意：systemd 托管需真实 Linux 系统的 systemd 环境；若代理为必需要求，可在 service 文件中追加一行 Environment=UNIFIED_PROXY_CONFIG=http://192.168.1.62:7897（每行仅一个 Environment=）。

五、安装方案 B：Docker Compose 部署（推荐稳定托管）

本方案使用官方 docker/docker-compose.yml 一键构建镜像并托管运行，适合长期驻留与跨机器迁移。

5.1 构建与启动

cd /opt/AIstudioProxyAPI/docker
docker compose up -d --build

⚠️ 注意：构建过程会在镜像内执行 camoufox fetch 与 Playwright 安装，首次构建耗时较长；如构建环境需代理，构建时传入 --build-arg PROXY_ADDR=http://192.168.1.62:7897。

5.2 Compose 配置要点

官方 docker/docker-compose.yml 关键内容（来源：仓库 v4.1.2_py）：

services:
  ai-studio-proxy:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    container_name: ai-studio-proxy-container
    mem_limit: ${DOCKER_MEMORY_LIMIT:-0}
    ports:
      - "${HOST_FASTAPI_PORT:-2048}:${DEFAULT_FASTAPI_PORT:-2048}"
      - "${HOST_STREAM_PORT:-3120}:${STREAM_PORT:-3120}"
    volumes:
      - ../auth_profiles:/app/auth_profiles
      - ../docker/.env:/app/.env:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${DEFAULT_FASTAPI_PORT:-2048}/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

逐项说明：

  • 认证目录挂载：../auth_profiles:/app/auth_profiles 为必需挂载，宿主机上的认证文件直接对容器内生效——推荐在宿主机完成 4.7 的登录保存认证，再交给容器运行；
  • 配置文件挂载：../docker/.env:/app/.env:ro 需先 cp docker/.env.docker docker/.env 再按需修改（只读挂载）；
  • 端口：宿主 2048 → 容器 2048（主 API）、宿主 3120 → 容器 3120（流式代理），经 HOST_FASTAPI_PORT/HOST_STREAM_PORT 环境变量改宿主侧端口；
  • 内存限制：mem_limit 默认 0（不限制），可在 docker/.env 中设 DOCKER_MEMORY_LIMIT=4g；
  • 健康检查：内置 /health 探活，30 秒间隔、3 次重试、40 秒启动宽限。

5.3 Docker 专用配置模板

官方提供 docker/.env.docker 模板，常用项：

HOST_FASTAPI_PORT=2048
HOST_STREAM_PORT=3120
UNIFIED_PROXY_CONFIG=http://192.168.1.62:7897
LAUNCH_MODE=headless

修改后重启生效：

docker compose up -d --force-recreate

5.4 验证与查看日志

docker compose ps
docker compose logs -f --tail 50
curl http://127.0.0.1:2048/health

⚠️ 注意：容器内访问 Google 依赖代理时，除 UNIFIED_PROXY_CONFIG 外，还应确认代理地址从容器内可达（如代理运行在宿主机，Linux 下可使用宿主机实际内网 IP 而非 127.0.0.1）。

六、方案对比与选择建议

维度方案 A：Python+Poetry 直跑方案 B：Docker Compose
上手难度中（自装系统依赖+Poetry）低（一键构建，依赖封装在镜像内）
环境隔离依赖装在系统 Python 环境完全隔离，不污染宿主
版本升级git pull + poetry install + camoufox fetch重新 build 镜像
排障便利性高（进程、日志、浏览器均在裸系统上可见）中（需进容器排查）
认证管理项目目录内直接读写经目录挂载共享宿主认证目录
适用场景首次接入、手动登录、快速排障、开发调试长期驻留、标准化部署、跨机器迁移

选择建议（与官方部署文档一致）：首次接入与排障用方案 A，长期稳定托管用方案 B；两者共用同一套 .env 参数与 auth_profiles/ 认证体系，可先 A 后 B 平滑切换。

七、配置说明

  • 配置文件：项目根目录 .env（从 .env.example 复制），所有环境变量在启动时读取；命令行参数优先级高于 .env；
  • 认证文件：auth_profiles/active/（当前生效）、saved/（可切换池）、emergency/（紧急池）；JSON 文件为 Playwright storage_state 格式（含 cookies 与 localStorage）；
  • 日志目录：logs/（启动日志 launch_app.log 等，应用启动后自动创建）；
  • 证书目录：certs/（可选，自定义 CA 时使用）；
  • Web UI：服务启动后访问 http://<服务器IP>:2048/，内置设置页可在线改代理、端口、密钥与查看日志（WS /ws/logs 实时推送）。

完整参数表与逐项解释见《AIstudioProxyAPI 配置参数详解》。

八、常见问题（FAQ）

Q1：launch_camoufox.py --help 都跑不起来，报 browserforge 数据文件 FileNotFoundError？ 模型定义文件（fingerprint-network.zip 等 5 个）需要联网下载，直连失败会中断启动。设置 http_proxy/https_proxy 环境变量后重跑（见 4.4 排障实录）。

Q2：模型文件下载成功但浏览器启动报 libgtk-3.so.0: cannot open shared object file？ 缺 GTK3 等系统库，按 4.5 的 apt 清单补装（官方 Dockerfile 同款清单）。

Q3：headless 启动报 No active profile found in '/opt/AIstudioProxyAPI/auth_profiles/active'？ active 目录没有认证文件。先 --debug 登录保存认证（4.7），或启用 --auto-auth-rotation-on-startup true。

Q4：启动报 Auth failed in headless mode, auth file update required？ 认证文件存在但已失效（日志中出现 Detected redirect to login page in headless mode）。重新走一次 --debug 登录保存，更新 active 下的 JSON。

Q5：直接 python server.py 报 CAMOUFOX_WS_ENDPOINT environment variable is missing？ server.py 只含 API 服务，必须由 launch_camoufox.py 拉起浏览器并注入端点；或自行运行 Camoufox 并在 .env 设置 CAMOUFOX_WS_ENDPOINT 连接外部浏览器实例。

Q6：报 Version information not found at /root/.cache/camoufox/version.json？ 未下载浏览器本体，执行 poetry run camoufox fetch。

Q7：端口被占用？ 启动器会在 Step 2 检查端口占用并报错；换端口用 --server-port <新端口>（如 --server-port 8150），或在 .env 改 PORT。

Q8：pip 装 Poetry 提示 root 警告？ 不影响功能；介意告警可新建普通用户安装运行，或用官方安装脚本 curl -sSL https://install.python-poetry.org | python3 - 装到用户目录。

九、卸载与清理

Python 直跑形态：

systemctl stop aistudio-proxy 2>/dev/null
systemctl disable aistudio-proxy 2>/dev/null
rm -f /etc/systemd/system/aistudio-proxy.service
systemctl daemon-reload
rm -rf /opt/AIstudioProxyAPI          # 项目目录（含认证文件，注意备份）
rm -rf /root/.cache/camoufox          # Camoufox 浏览器本体（约 2.4GB）
rm -rf /root/.cache/pypoetry          # Poetry 虚拟环境
pip3 uninstall -y poetry              # Poetry 本体（可选）

Docker 形态：

cd /opt/AIstudioProxyAPI/docker
docker compose down --rmi local       # 停止并删除容器与本地构建镜像
rm -rf /opt/AIstudioProxyAPI

卸载前如需保留认证，先备份 auth_profiles/active/ 下的 JSON 文件。

十、参考链接

  1. 官方仓库：https://github.com/CJackHwang/AIstudioProxyAPI
  2. 官方快速开始：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/quick-start.md
  3. 官方部署与运维指南：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/deployment-and-operations.md
  4. 官方认证配置文档：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/authentication-setup.md
  5. Docker 说明：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docker/README-Docker.md
  6. Releases（版本取证，查询日期 2026-10-23）：https://github.com/CJackHwang/AIstudioProxyAPI/releases
  7. 本专栏相关篇目：《AIstudioProxyAPI 介绍与选型指南》《AIstudioProxyAPI 配置参数详解》《AIstudioProxyAPI 常用 CLI 命令与工具详解》