Linux 安装指南

更新时间：2026-08-21 11:55:33 阅读：35 收藏：0 收藏
# Linux 安装指南

> **读者**：已从产品页下载 `go-ai-platform-linux-amd64.zip` 的客户或客户侧运维。  
> **不包含**：如何从源码编译、打 zip、上传作品页——那些是厂商交付流程。

## 你需要准备什么

| 项目 | 说明 |
|------|------|
| 系统 | Ubuntu 22.04+ / Debian 12+ / RHEL 8+（x64）建议 |
| 硬件建议 | 4 核 / 8 GB / 系统盘 40 GB+ |
| 安装包 | 产品页提供的 `go-ai-platform-linux-amd64.zip` |
| 权限 | 安装脚本需 `sudo` |
| 依赖 | PostgreSQL **18.x**、Redis **7.x**（可复用本机已有；也可按脚本提示安装） |

默认不捆绑 Docker / MinIO；素材默认落在本机目录。宝塔等面板环境可用，注意 PostgreSQL 扩展 `pgcrypto` 可用。

## 安装步骤

```bash
unzip go-ai-platform-linux-amd64.zip
cd go-ai-platform-linux-amd64   # 以包内实际目录名为准

sudo ./scripts/install.sh \
  --pg-password '你的PostgreSQL密码' \
  --admin-password '至少12位管理端密码' \
  --client-secret '至少16位Client密钥'
```

说明：

- `--pg-password`：数据库登录密码（面板「管理员密码」或你创建的业务用户密码）。
- `--admin-password`：**本平台**后台 admin 密码，与面板账号无关。
- `--client-secret`：server 与 client 共享密钥。

本机已有 PostgreSQL / Redis 时，脚本默认**复用**，不会强行重装。

常用验收：

- `http://127.0.0.1:8080/health`
- C 端：`http://127.0.0.1:8080/`
- 管理端：`http://127.0.0.1:8080/admin/`

## 启停（systemd）

```bash
sudo systemctl status go-ai-server go-ai-client
sudo systemctl restart go-ai-server go-ai-client
sudo journalctl -u go-ai-server -u go-ai-client -f
```

前台排障可用包内 `scripts/start-foreground.sh`（以包内说明为准）。

## 首次登录后建议做的事

1. 登录 `/admin/`，确认品牌与系统设置。
2. 配置 Provider / 模型（密钥只留在你方环境）。
3. 按约定完成授权激活。
4. C 端跑通一条最小任务。

## NowVoice（语音能力）依赖

若你启用了 NowVoice 一类语音能力，而管理端消费节点探测为「未安装」或 error：

1. **优先**：在管理端打开对应消费节点 / Client，对 NowVoice 使用 **「安装工具」**，等待完成后再点探测。
2. 外网或镜像异常时，可在 **client 工作目录**手工安装（裸机默认 `/opt/go-ai/client`）：

```bash
cd /opt/go-ai/client/data/tools/nowvoice
mkdir -p out
python3 -m venv venv
./venv/bin/python -m pip install -r requirements.txt
# 国内镜像示例（可选）：
# ./venv/bin/python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

./venv/bin/python -m playwright install chromium
# 缺系统库时（需 root）：
# ./venv/bin/python -m playwright install-deps chromium

./venv/bin/python -c "from playwright.sync_api import sync_playwright; print('ok')"
```

前置：系统已装 `python3`（含 venv）。目录内应有 `tts.py` 与 `requirements.txt`；若缺失，先在后台点一次「安装工具」写出布局，再重试手工步骤。站点需登录时，按交付说明在同目录放置登录态文件。装完后回到管理端再探测，状态应为「已安装」。

## 防火墙与安全

- 对外只暴露 HTTPS 反代后的业务端口。
- **不要**对公网开放 `5432`、`6379`、`/internal/*`。

## 卸载

```bash
sudo ./scripts/uninstall.sh
```

卸载**不会**删除系统级 PostgreSQL / Redis，也不会默认丢弃业务库数据（以脚本提示为准）。

## 常见问题

| 现象 | 处理 |
|------|------|
| `psql` 找不到 | 面板环境把 PostgreSQL `bin` 路径传给安装参数（如 `--pg-bin`），或把该目录加入 PATH 后再装 |
| 缺 `pgcrypto` | 在面板/发行版中为当前大版本启用 contrib；或换用带 contrib 的官方包 |
| client 不在线 | 查 `systemctl status go-ai-client` 与密钥是否与 server 一致 |
| NowVoice 失败 | 见上文；仍失败请附《问题采集清单》联系支持 |

下一步：

- [首次配置指南](/doc-2)
- [授权激活说明](/doc-7)
- [运维、升级、备份与恢复手册](/doc-5)
评论区
