93 lines
9.2 KiB
Markdown
93 lines
9.2 KiB
Markdown
# 阿里云单机演示部署
|
||
|
||
该配置用于单机公网演示，不是生产验收配置。只向公网发布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不得进入`.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)。
|