# 环境、配置与兼容性

星线 App、聊天服务与 Account 必须使用匹配环境。本页解释配置契约与变更影响；变量明细及本地命令见[开发配置](https://document.thestarline.cn/app/development.md)，生产变更步骤见[运维](https://document.thestarline.cn/app/operations.md)。公开资料不包含任何实际密钥或私有配置文件。

## 环境一致性

| 环节 | 需要匹配的内容 | 配错的表现 |
| --- | --- | --- |
| App → 聊天服务 | API 基地址、HTTPS、回跳 scheme、客户端 state | 登录回到错误 App、换票失败、会话不能恢复 |
| 聊天服务 → Account | issuer、client ID、机密凭据、回调地址和授权范围 | 授权端拒绝、token 交换失败或用户信息不可读 |
| Account 浏览器 | 来源、Cookie、RP ID、可信代理 | 会话丢失、通行密钥失败、Host 或来源被拒绝 |
| 通话 | LiveKit 地址、签发配置与设备网络 | 信令已接收但房间或媒体不可用 |
| 城市、识别、推送 | 城市数据库、模型、APNs 与对应平台配置 | 相关功能受限，而非整个服务必然失败 |

开发环境的 localhost、Android 模拟器宿主别名与真机网络地址各有用途。Release 包应核对真正的服务器地址和回调配置，不能把调试覆盖或本地 fixture 配置带入分发产物。

## 原生端配置

iOS 的 `STARLINE_CHAT_BASE_URL` 仅用于 Debug 覆盖；HTTP 仅允许回环。默认聊天地址为 `https://chat.thestarline.cn`。最低系统为 iOS 17，Swift 语言版本为 6；当前工程以 iPhone 为设备家族，iPad 与 watchOS 不能由此自动推断已交付。

Android 的 `starlineChatBaseUrl` 是构建属性，默认同样指向正式聊天服务。原生授权地址校验只信任正式 Account HTTPS 来源，没有 Debug localhost 例外；仅覆盖聊天基地址不能完成隔离 Account 原生登录。最低 API 26，目标/编译 API 35，Java 17。当前仓库声明 AGP 8.7.3 和 Gradle Wrapper 9.2.1；这一组合需要在所选环境实际验证兼容性，本技术文档没有执行新的原生构建。构建成功还需要继续检查签名、manifest、实际 API 地址和真机行为。

## 服务启动和可选能力

聊天服务要求 Node.js 24 或以上，使用内置 SQLite；Account 使用独立 MySQL。聊天数据库、身份数据库、静态文档内容和设备本地数据不是同一数据集。服务的健康 HTTP 响应不自动覆盖外部身份、模型、媒体或推送依赖。

`CHAT_CRYPTO_NODE_BUNDLE` 指向 MLS 验证器产物；配置该产物不会自动切换所有客户端的主消息路径。`CHAT_MEMORY_MODEL_URL` 与模型名称配置影响服务器识别适配器，而不是启用记忆云同步。APNs 和 LiveKit 的可用性既受配置影响，也受证书、网络、设备和平台状态影响。

`CHAT_PROFILE_ENCRYPTION_KEY` 等持久密钥与既有资料有关。轮换前需分析解密、索引、会话和回滚影响，不能把随意重建配置当作故障修复。客户端只保存必要会话材料，服务端机密凭据不得放入 App 包、下载脚本或公开文档。

## 配置变更的检查顺序

1. 识别变更归属：设备、聊天、Account、媒体、推送或静态站。
2. 核对当前运行基线与目标版本，保留可恢复的配置和数据，不回显实际值。
3. 在隔离环境验证格式与依赖；测试只使用合成账号和合成数据。
4. 对原生包重新构建并核对产物；对服务执行对应配置、迁移和健康检查。
5. 运行真实路径：授权回跳、换票、会话恢复及受到影响的业务步骤。
6. 记录已验证范围、未覆盖设备和待办，不把一个检查结果推广为全部能力通过。

## 文档站的配置

技术文档由 Markdown 生成静态文件，没有服务端账号、数据库或访问令牌。站点基本地址固定为 `https://app.thestarline.cn`，构建时同步生成 canonical、站点地图和索引文件。部署只需要静态产物以及正确的 Markdown MIME；不需开放 Account 或聊天权限。构建说明保存在文档源目录的维护指南，公开抓取规则见[文档访问与引用](https://document.thestarline.cn/app/ai-access.md)。