story/deploy/server

阿里云单机演示部署

该配置用于单机公网演示，不是生产验收配置。只向公网发布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的服务器专用配置：

./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镜像后执行：

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执行和最终字幕补传。

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路径。

自动备份与恢复校验

首次安装定时任务：

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校验；当前单机配置不把这些文件级检查冒充跨故障域生产恢复。

手工验证已有备份：

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

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

健康监测与告警

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通知。完整检查项、签名规则、阈值和失败分支见《单机云端健康监测与告警手册》。

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

OSS异地备份适配

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异地备份适配与门禁》。

首次设备认证与绑定（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。详细配置与验证见实施说明。