AngeVoice 快速开始

选择合适的运行画像，启动服务并确认模型与健康状态。

一键安装（推荐普通用户）

服务器已安装 Docker 和 Docker Compose V2 后，可直接运行交互式安装脚本。脚本会自动检测 CPU/GPU、Docker/Compose、GitHub、Docker Hub 与本机 Docker registry mirror。检测到 NVIDIA GPU 时默认推荐通用 gpu 画像；legacy-gpu 仅用于 gpu 无法启动或 CUDA/cuDNN 不兼容的环境。

bash <(curl -fsSL https://raw.githubusercontent.com/AngeVox/AngeVoice/main/scripts/install.sh)

如果你在国内网络访问 GitHub 或 Docker Hub 较慢，可以先下载源码包后执行本地脚本：

git clone https://github.com/AngeVox/AngeVoice.git
cd AngeVoice
bash scripts/install.sh

默认 Docker 配置集中在 docker/angevoice.env，CPU/GPU/Legacy 使用统一持久化契约；管理后台默认启用，首次可使用 admin / admin123 进入并获取 API Key，公网暴露前必须在安全页修改凭据；gpu 是推荐的 NVIDIA 画像，legacy-gpu 是兼容画像。

在已下载的源码目录中运行脚本时，会直接就地安装或更新；使用远程 curl 安装时，如本机尚无项目目录，脚本会自动准备完整仓库到 /opt/angevoice。安装完成后会读取本机局域网 IP，并输出可访问地址，例如 http://192.168.1.10:8101。

生产 Docker 模板默认 KOKORO_API_KEY=auto。首次启动会自动生成 API Key 并写入：

/opt/angevoice/credentials/.angevoice-api-key
# 查看命令
cat /opt/angevoice/credentials/.angevoice-api-key

请把这个 token 粘贴到 Studio 设置里的 Bearer Token。新部署可使用默认管理凭据 admin / admin123 首次进入后台；进入后会显示安全警告，公网暴露前必须修改为自定义用户名与密码，修改后的凭据只以 PBKDF2 哈希持久化。也可在启动前通过本地 docker/angevoice.local.env 覆盖默认凭据。

管理后台登录凭据：

Docker 部署模板提供 admin / admin123 作为首次进入路径，便于普通用户访问控制台与 API Key；后台会显著提示其风险。管理员用户名支持中文，修改后的凭据由独立 credentials/ 卷保存为 PBKDF2 哈希。生产/公网部署必须先改密，或在启动前通过不提交仓库的本地覆盖文件预设凭据。

安装完成后脚本会创建 AngeVoice 管理命令。以后直接输入：

AngeVoice

即可打开菜单，执行安装/更新、重启、停止、卸载、查看状态和访问地址。也可以直接执行：

bash scripts/install.sh --status
bash scripts/install.sh --restart
bash scripts/install.sh --stop
bash scripts/install.sh --uninstall

卸载只停止并移除容器/网络，不删除模型、输出和配置文件。

快速开始

Docker GPU

git clone https://github.com/AngeVox/AngeVoice.git
cd AngeVoice/docker/gpu
sudo docker compose up -d

默认访问：

http://localhost:8101

检查服务：

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

容器健康状态：每个 Docker 镜像内置 HEALTHCHECK，每 30 秒自动请求 /health 端点。返回 {"status":"ok"} 或 {"status":"idle"} 都判定为 healthy；idle 表示模型已被空闲卸载但服务正常可用。start-period=300s 确保模型加载期间不会误判。可用 docker inspect --format='{{json .State.Health}}' <container> 查看。

Docker CPU / legacy-gpu 兼容模式

# CPU，默认端口 8100
cd docker/cpu && sudo docker compose up -d

# legacy-gpu，默认端口 8102
# 仅在 docker/gpu 无法启动或 CUDA/cuDNN 不兼容时使用。
cd docker/legacy-gpu && sudo docker compose up -d

有 NVIDIA GPU 时建议先试 docker/gpu；legacy-gpu 面向无法使用标准 GPU 镜像的旧驱动或兼容环境。

国内镜像加速

Docker Compose 默认使用 Docker Hub（maxblack777/angevoice-*:v2.6.616）拉取当前版本镜像。国内网络访问 Docker Hub 较慢时，可通过 Docker 镜像站加速：

# 方案 1：临时使用镜像站拉取（替换 registry-1.docker.io 为镜像站地址）
docker pull docker.1ms.run/maxblack777/angevoice-gpu:v2.6.616
docker tag docker.1ms.run/maxblack777/angevoice-gpu:v2.6.616 maxblack777/angevoice-gpu:v2.6.616

# 方案 2：配置 Docker daemon 全局镜像加速（推荐）
# 编辑 /etc/docker/daemon.json，添加：
# { "registry-mirrors": ["https://docker.1ms.run"] }
# 然后重启 Docker：sudo systemctl restart docker

常用镜像站：docker.1ms.run、docker.xuanyuan.me、dockerpull.org。镜像站可用性可能变化，如遇问题请更换其他镜像站。

/health 状态语义

/health 返回 HTTP 200 不代表当前模型一定常驻内存，需结合 status 字段：

Docker 健康检查把 ok 和 idle 都视为 healthy。

文档入口

端口和接口速览

在 GitHub 查看原始文档 ↗