# 阿里云单机演示部署

该配置用于单机公网演示，不是生产验收配置。只向公网发布HTTP 80和HTTPS 443；PostgreSQL、Redis、MinIO、Keycloak内部端口以及API/Worker端口均不映射到宿主机。当前阿里云演示机使用Let's Encrypt短期IP证书，`certbot-ip-renew.timer`负责自动续期。单机备份覆盖PostgreSQL、Redis、MinIO对象和当前Keycloak数据目录，并执行数据库级隔离恢复校验；五分钟健康检查覆盖部署模式、公网入口、OIDC、容器、模拟服务、备份、外部告警、证书、定时任务和磁盘。跨故障域备份、真实告警接收器、真实RTC、模型、内容安全和云KMS仍按阶段8验收清单执行。

无法直接从Git拉取或需要冻结当前工作树时，可先在开发机执行`powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-server-deployment-bundle.ps1 -Version 0.76.0-rc.hardware1`，再用`powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-server-deployment-bundle.ps1 -Archive .\.deploy-artifacts\data-terminal-cloud-0.76.0-rc.hardware1.zip`验证。归档包含`deploy-manifest.json`和`SHA256SUMS`，不会打包`.env`、设备/供应商密钥、本地运行目录、`node_modules`或构建缓存。上传服务器后必须再次核对归档侧车`.sha256`和包内清单，再覆盖候选目录；服务器现有`deploy/server/.env`及`/etc/data-terminal-cloud`密钥目录不得从归档替换。

服务器至少需要Docker Engine 29与Compose 2.40。首次部署先生成权限为600的服务器专用配置：

```sh
./deploy/server/bootstrap-secrets.sh \
  https://SERVER_IP \
  0.64.0-rc.cloud1 \
  FULL_GIT_COMMIT \
  2026-08-26T00:00:00Z
```

载入同一候选版本的`data-terminal-cloud-backend`和`data-terminal-cloud-web`镜像后执行：

```sh
chmod 0755 deploy/server/*.sh
docker compose -f compose.yaml -f deploy/server/compose.override.yaml \
  --env-file deploy/server/.env up -d --no-build \
  postgres redis minio keycloak migrate seed mock-alert-receiver callbacks \
  mock-provider api worker web gateway
docker compose -f compose.yaml -f deploy/server/compose.override.yaml \
  --env-file deploy/server/.env up -d --no-build --force-recreate --no-deps gateway
```

从Windows生成的压缩包解开后必须恢复脚本执行位。若`current`是切换到新发布目录的符号链接，还必须强制重建Gateway；否则Docker会继续使用旧发布目录已解析的Nginx绑定挂载，新增路由不会生效。

安全组和主机防火墙只保留TCP 80、443以及受限来源的SSH 22。HTTP 80仅用于跳转到标准HTTPS 443。正式环境仍应配置自有域名、生产OIDC和真实外部服务，并切换到Kubernetes生产覆盖层。

需要在演示机接入真实RTC、豆包语音和方舟摘要时，把凭据文件以`0600`权限放入`/etc/data-terminal-cloud/voice-runtime`，并在`deploy/server/.env`设置`RTC_TOKEN_ISSUER=volcengine`、`VOICE_PROVIDER=volcengine`、`RTC_APP_ID`、`CONTENT_GENERATOR`和`ARK_CONTENT_MODEL`。Compose只读挂载该目录，敏感值不进入源码、镜像或环境文件。

切换火山硬件对话智能体时，维护中心逐台只需把`voice_runtime`设为`volc_hardware_agent`，不填写设备级Bot。平台代设备动态注册时，在`deploy/server/.env`设置`VOLC_HARDWARE_PROVISIONING_ENABLED=true`、`VOLC_HARDWARE_INSTANCE_ID`、`VOLC_HARDWARE_PRODUCT_KEY`、`VOLC_HARDWARE_AGENT_BOT_ID`、`VOLC_HARDWARE_AGENT_TRANSPORT`、`VOLC_HARDWARE_AGENT_MINIMUM_SDK_VERSION`、`VOLC_HARDWARE_PRODUCT_SECRET_FILE=/run/secrets/voice-runtime/volc-hardware-product-secret`和独立随机的`VOLC_HARDWARE_DEVICE_CREDENTIAL_MASTER_KEY`；将Product Secret以单行、`0600`权限写入`/etc/data-terminal-cloud/voice-runtime/volc-hardware-product-secret`。旧设备代理注册流程的Product Secret不下发给设备；新设备ONBOARDING-1.1按附件E.2通过认证后的HTTPS加密配置下发。Product Secret不得进入`.env`、源码、日志或镜像。设备首次预配时，平台根据这些产品默认值自动创建火山绑定并调用DynamicRegister；火山从产品额度中分配License，平台只加密保存并下发本设备的一机一密Device Secret，不下发License明文。发布前必须验证平台代理注册、默认Bot绑定、每次会话上下文注入、`session.updated`确认后激活、`session_updated`存活上报、`stop_session`执行和最终字幕补传。

```sh
sudo install -d -m 0700 /etc/data-terminal-cloud/voice-runtime
sudo sh -c 'umask 077; read -r product_secret; printf "%s" "$product_secret" > /etc/data-terminal-cloud/voice-runtime/volc-hardware-product-secret'
```

上面的`read`从终端读取，不要把真实Product Secret写进Shell历史。启用前确认默认Bot关联的产品与`VOLC_HARDWARE_PRODUCT_KEY`完全一致；Device Name由`dt-`加平台设备UUID稳定生成。密钥文件或产品默认配置缺失、格式错误时API拒绝启动，未启用时凭据接口明确返回`HARDWARE_AGENT_PROVISIONING_UNAVAILABLE`。

设备HMAC密钥由`device_credential`表以AES-256-GCM密文保存。`deploy/server/.env`中的`DEVICE_CREDENTIAL_MASTER_KEY`只负责数据库密文的认证解密，不得写入数据库或设备；既有`DEVICE_LOCAL_SECRET`只用于首次部署升级时导入两台演示设备，确认数据库凭据记录完整后可移除。新增、轮换和吊销设备密钥使用后端镜像内的`/app/device-credential`维护命令，生成的设备明文密钥只显示一次。

通话内记忆工具只通过网关精确开放`/internal/v1/tools/memory-search`，请求必须携带平台为当前通话签发的短期任务令牌。`MEMORY_TOOL_SIGNING_SECRET`必须是服务器独立随机密钥，不得与游标签名、分享签名或RTC密钥复用；网关不会开放其他`/internal`路径。

## 自动备份与恢复校验

首次安装定时任务：

```bash
chmod 0755 deploy/server/backup.sh deploy/server/verify-backup.sh deploy/server/install-backup.sh
sudo deploy/server/install-backup.sh
sudo systemctl start platform-backup.service
sudo systemctl status platform-backup.service --no-pager
```

备份以AES-256-CBC、PBKDF2和独立随机口令加密，默认保存在`/var/backups/data-terminal-cloud`并保留14天。每次定时任务会实际把PostgreSQL恢复到随机隔离数据库，对比迁移状态、客户组织、账号、表和外键计数，再删除临时数据库。Redis RDB、MinIO对象和暂停后的Keycloak数据目录会进入同一加密归档并进行逐文件SHA-256校验；当前单机配置不把这些文件级检查冒充跨故障域生产恢复。

手工验证已有备份：

```bash
sudo deploy/server/verify-backup.sh /var/backups/data-terminal-cloud/platform-YYYYmmddTHHMMSSZ.tar.gz.enc
```

加密口令位于`/etc/data-terminal-cloud/backup-passphrase`且仅root可读。必须把该口令和加密备份复制到不同故障域；口令丢失将无法恢复备份。

## 健康监测与告警

```bash
chmod 0755 deploy/server/health-monitor.sh deploy/server/install-monitoring.sh
sudo deploy/server/install-monitoring.sh
sudo systemctl start platform-health-monitor.service
sudo systemctl show platform-health-monitor.service -p Result -p ExecMainStatus
python3 -m json.tool /var/lib/data-terminal-cloud-monitor/status.json
```

监测任务每五分钟执行，正常状态为`healthy`。默认`HOST_DEPLOYMENT_PROFILE=demo`，要求两个模拟服务完整运行；切到`production`后则要求模拟服务全部停止。它还要求宿主机所有非回环TCP监听只能使用22、80和443，避免安全组误放行与错误容器端口映射叠加后暴露数据库或缓存。默认只记录结构化状态和systemd日志；在`/etc/data-terminal-cloud/monitor.env`配置`ALERT_WEBHOOK_URL`后，状态变化会发送带时间戳和HMAC-SHA256签名的JSON通知。完整检查项、签名规则、阈值和失败分支见[《单机云端健康监测与告警手册》](../../docs/server-health-monitoring.md)。

生产候选不能只修改部署模式。生产验收快照同时要求：`HOST_DEPLOYMENT_PROFILE=production`；API、Callbacks和Worker实际容器`APP_ENV=prod`；Keycloak不使用`start-dev`；OSS异地备份最近一次上传与回读验证成功；真实外部告警接收器已配置；`mock-provider`和`mock-alert-receiver`均不运行。任一条件缺失都会阻断生产基础设施门禁，但不会影响`LAB`或`STAGING`联调。当前Compose覆盖层固定为演示用途，不能通过改标签升级成生产部署。

## OSS异地备份适配

```bash
chmod 0755 deploy/server/install-ossutil.sh \
  deploy/server/install-offsite-backup.sh \
  deploy/server/sync-backup-offsite.sh
sudo deploy/server/install-offsite-backup.sh
```

安装后默认为禁用状态，不会访问OSS。默认认证方式为`ecs_ram_role`，使用`cn-hangzhou`地域端点并强制先通过IMDSv2确认实例角色，不保存长期AccessKey。创建私有Bucket并绑定最小权限ECS RAM角色后，在`/etc/data-terminal-cloud/offsite-backup.env`填写Bucket和前缀、设置`OFFSITE_BACKUP_ENABLED=true`与`OFFSITE_BACKUP_REQUIRED=true`，再手工启动一次`platform-offsite-backup.service`。任务会上传加密归档及摘要、重新下载并复算SHA-256；健康检查在启用后强制要求最新本机归档已有对应远端验证。配置和真实验收步骤见[《阿里云OSS异地备份适配与门禁》](../../docs/offsite-backup.md)。


## 首次设备认证与绑定（2026-09-12）

新设备使用ONBOARDING-1.1。叠加`deploy/server/compose.onboarding.yaml`，设置ONBOARDING_RELEASE_VERSION与实际网关网段ONBOARDING_TRUSTED_PROXY_CIDRS；主密钥使用服务器`/etc/data-terminal-cloud/voice-runtime/onboarding-master-key`。先备份再迁移至58，更新API、worker和web，并重建gateway使新的Nginx挂载生效。仅HTTP `POST /api/v1/device/time-challenges`直达API；其余HTTP继续跳转HTTPS。详细配置与验证见[实施说明](../../docs/onboarding-implementation.md)。