Astra GateEnglish

配置与数据目录

~/.astra 布局、启动配置与安全边界

数据目录

一切状态都在 ~/.astra(环境变量 ASTRA_HOME 可覆盖整个根目录):

路径内容
config.json启动配置:端口、监听地址等(服务启动前读取)
runtime.json实际运行状态:pid、端口、apiVersion
install.json安装记录(桌面端解析服务二进制时使用)
astra.dbSQLite(WAL):请求记录、提供商、模型、设置
keys/密钥材料;权限收紧为仅当前用户可读写
logs/服务日志(astra logs 读这里)
backups/db/数据库迁移前自动备份
backups/client-configs/客户端配置备份:首次修改前的备份永久保留,另有约 20 份滚动备份
bodies/开启「保存请求与响应内容」后的请求体存储

端口可能漂移

config.json 里的端口只是期望值。启动时若被占用,Astra 会挑一个可用端口并把实际值写入 runtime.json。任何脚本都不要假设配置端口 = 实际端口:

命令bash
cat ~/.astra/runtime.json

管理密码与对外监听

命令bash
astra config set-password     # 先设密码
astra start --host 0.0.0.0    # 再对外监听

也可以在控制台的设置 → 网关 → 监听里切换(没有密码时会先要求设置),重启服务后生效。

安全边界由服务端统一强制:

  • Host 白名单 — 只监听本机时,Host 头不是 127.0.0.1 / localhost 的请求会被拒绝,防御 DNS 重绑定;
  • 管理头 — 所有「修改」类 /api 请求必须携带 X-Astra-Admin: 1(Web 控制台自动携带);
  • 会话 — 对外监听时,只有本机请求(回环地址连入、Host 为回环名、没有代理转发头)免登录,其余请求除白名单路径外都要求会话 cookie(登录页签发);
  • 令牌 — 来自其他设备的网关请求始终需要令牌,「要求访问密钥」开关只对本机生效;设置密码、修改监听地址只接受本机请求;
  • 密钥加密 — 上游 API Key 与本地客户端密钥用 DataProtection 加密存储,接口只回传掩码。

运行时可调设置

不需要改文件、不用重启的设置(主题、语言、请求体保存、保留期、推理强度换算、隐私护栏总开关等)存在数据库的单一 JSON 设置里,从控制台「设置」页修改即时生效。

环境变量

变量作用
ASTRA_HOME替换数据目录根(多实例 / 备份还原时有用)
ASTRA_SERVER_BIN桌面端开发时手动指定服务端二进制路径