# Avatar Compose 离线安装

## 系统要求

- Linux x86_64/amd64 或 ARM64
- 推荐 8 核 CPU、16 GiB 内存、300 GiB 数据盘
- root 权限
- 无需预装 Docker；制品包含 Docker Engine 29.3.0 与 Compose v2
- 默认桥接网络依赖系统的 `iptables` 包，需提前安装（Docker 离线包不包含它）

Ubuntu/Debian 可在联网时执行 `apt-get update && apt-get install -y iptables`；
RHEL/CentOS 使用 `dnf install -y iptables`（旧版使用 `yum`）。完全离线的主机需提前准备并安装匹配发行版的依赖包。

## 下载与校验

```bash
version=<avatar-version>
arch=amd64
base=https://cdn.zhama.com.cn/tego-os/${version}

wget "${base}/tego-avatar-compose-${version}-${arch}.tar"
wget "${base}/tego-avatar-compose-${version}-${arch}.tar.sha256"
sha256sum -c "tego-avatar-compose-${version}-${arch}.tar.sha256"
```

校验失败时不要解压或安装。

## 一步安装

```bash
mkdir -p tego-avatar
tar xf "tego-avatar-compose-${version}-${arch}.tar" -C tego-avatar
cd tego-avatar
sudo ./setup.sh install
```

安装脚本会提示输入私有化 License。直接回车将以受限模式完成安装并跳过 LDAP 配置；非交互安装可使用 `--license '<license-token>'`。

不要再手工执行 `docker load`。安装脚本会校验 `manifest.json`、`docker.arch`、`images/IMAGES` 和全部 SHA256 后，以 `--pull never` 启动服务。

## 验证

```bash
sudo ./setup.sh status
curl -fsS http://127.0.0.1:5178/
```

产品入口：

```text
http://<服务器 IP>:5178
```

默认管理员：

- 用户名：`zhama`
- 邮箱：`zhama@zhama.com`
- 密码：安装结束时输出，并保存在 `.secrets`

## 端口

唯一发布到宿主机的端口：

- `5178/tcp`：Studio，绑定 `0.0.0.0`；必须通过防火墙或安全组限制访问范围

tego-server、tego-traefik、tego-mcp、LibreOffice、PostgreSQL、Redis、OpenLDAP、
Garage 和 Garage WebUI 均不发布宿主机端口。

## 手机推送配置

推送默认关闭。升级镜像不会自动创建或填写凭据；需要在部署目录的 `host/.env` 配置：

```dotenv
PUSH_NOTIFICATION_ENABLED=true
FCM_SERVICE_ACCOUNT_JSON='{"project_id":"项目 ID","client_email":"服务账号邮箱","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"}'
JPUSH_APP_KEY=与客户端一致的极光AppKey
JPUSH_MASTER_SECRET=极光服务端MasterSecret
JPUSH_APNS_PRODUCTION=true
JPUSH_ANDROID_PACKAGE_NAME=com.zhama.live.ai
```

tego iOS / Google Play 使用 FCM，tego Android OSS 和私有品牌使用各自极光；只需配置该部署实际服务的渠道。
当前每个 Server 部署支持一组极光凭据，不能用官方应用的凭据替代其他私有品牌的凭据。
上例包名对应 tego OSS；私有品牌必须改成其实际 Android applicationId。未配置包名时极光通知只能按兼容路径打开首页，不能跳转到指定话题。
FCM JSON 必须单行并用单引号包裹，保留私钥的字面量 `\n`。私钥仅保存在权限 `0600` 的服务端配置，不能进入客户端或代码仓库。

备份 `.env` 后只重建 Server，使环境变量生效（会短暂中断 API）：

```bash
cd host
chmod 600 .env
docker compose --env-file .env -f docker-compose.yml config --quiet
docker compose --env-file .env -f docker-compose.yml up -d --no-deps --pull never --wait tego-server
```

检查 Server 健康状态，以及日志中的供应商初始化和推送 worker 启动结果。
供应商凭据校验通过后，还需安装带匹配配置的新包，在真机上验证后台收件和通知点击；只更新 Server 不会改变历史 App 的推送供应商。

## 重试、升级与卸载

安装中断后可在同一目录原地重试：

```bash
sudo ./setup.sh install
```

若 Docker 日志提示 `failed to create NAT chain DOCKER: iptables not found`，先安装上述 `iptables` 依赖，
再清除 systemd 的启动失败计数并启动 Docker，确认 Server 信息可读后重试安装：

```bash
sudo systemctl reset-failed docker
sudo systemctl start docker
sudo docker info
sudo ./setup.sh install
```

升级：

```bash
sudo ./setup.sh upgrade
```

保留数据卸载：

```bash
sudo ./setup.sh uninstall
```

永久删除：

```bash
sudo ./setup.sh uninstall --purge
# 或带二次确认
sudo ./clean.sh
```

详细运维与备份说明见 `README.md` 和 `OPERATIONS.md`。

### Apple 登录（官方 iOS 应用）

开启 Apple 登录需要新版 Server，App ID 启用 Sign in with Apple，并重新生成包含该能力的签名描述文件。
把专用登录密钥放入部署目录 `host/secrets/apple-sign-in.p8`，目录权限 `700`、文件权限 `600`；Compose 以只读方式挂载到 `/run/tego-secrets`。
在部署环境配置：

```dotenv
AUTH_APPLE_ENABLED=true
APPLE_CLIENT_IDS=com.zhama.live.ai
APPLE_TEAM_ID=<Apple Team ID>
APPLE_SIGN_IN_KEY_ID=<Apple 登录 Key ID>
APPLE_SIGN_IN_PRIVATE_KEY_FILE=/run/tego-secrets/apple-sign-in.p8
```

密钥只用于服务器交换和撤销 Apple 授权；不能复用 APNs 专用密钥。Apple 刷新令牌使用服务端凭据加密服务存储。
注销会先撤销 Apple 授权，再清理用户数据；撤销失败时保留账号供重试。
Kubernetes 部署需将 .p8 通过 Secret 只读挂载，并把 `APPLE_SIGN_IN_PRIVATE_KEY_FILE` 指向对应容器路径。

### Apple 内购审核

TestFlight 和 App 审核使用 Apple 沙盒购买。生产环境保留默认的沙盒收据拦截，
仅将专用审核/验收账号的服务器用户 ID 填入 `BILLING_APPLE_SANDBOX_USER_IDS`
（多个 ID 用逗号分隔）。此配置仅放行 Apple 已验证的 iOS 沙盒收据，其他用户及
Android 沙盒购买不受影响；不要为正式服务全局开启 `BILLING_ALLOW_SANDBOX`。
账号 ID 取自服务器，不接受客户端传入的审核标记，真实账号信息不得写进模板或仓库。
更新 Server 镜像并重建容器后生效。审核结束后可移除此名单并重建容器。