READ / 带走
- 先确认下载包对应当前操作系统和处理器架构
- 升级前保留项目导出或版本控制基线
- 不要把会话正文、凭证和项目文件混成一份备份
选择安装来源
普通用户应从官网下载区获取与当前操作系统和架构匹配的安装包。仓库当前面向 Windows、macOS 和 Linux；官网下载区没有列出的平台或架构没有可替代的安装包。
Windows x64 提供三种格式：普通用户优先使用 Inno .exe 安装器，它接入应用内自动更新；需要标准 Windows Installer 部署时使用 .msi；不希望安装时可解压 .zip 后直接运行 Astravia.exe。MSI 和 ZIP 是补充下载格式，应用内自动更新仍通过 Inno 安装器完成。
Linux 当前发布 x64 架构的三种格式：AppImage 适合免安装运行，DEB 适合 Debian/Ubuntu，RPM 适合 Fedora/RHEL 系发行版。下载后可按格式安装：
VERSION=x.y.z # 替换为下载的版本号
# Debian / Ubuntu
sudo apt install "./astravia_${VERSION}_amd64.deb"
# Fedora / RHEL 系；当前直接下载的 RPM 尚未做 GPG 签名
sudo dnf install --nogpgcheck "./astravia-${VERSION}.x86_64.rpm"
# AppImage
chmod +x "./Astravia-${VERSION}.AppImage"
"./Astravia-${VERSION}.AppImage"DEB/RPM 当前是通过 HTTPS 直接分发的安装包，不是 APT/DNF 软件源。安装后，应用更新器会继续选择与当前安装方式相同的包格式。
源码开发者从仓库运行桌面端时需要 Bun 1.3+ 和 Node.js 20+，并使用 apps/desktop 下的开发命令。开发环境默认使用独立数据目录，避免覆盖已安装版本的数据。
开源版与商业版
桌面端的构建模式在打包时确定，不是安装后的运行时开关：
| 模式 | 登录与云服务 | 能力来源 | 共同能力 |
|---|---|---|---|
| 开源版 / serv-less | 不包含账户、订阅和远程模型目录 | GitHub 能力源 | 本地会话、BYOK、插件、主题、IM、知识库 |
| 商业版 / Astravia Serv | 可包含登录、组织、订阅和官方目录 | 官方服务端能力源 | 本地会话、BYOK、插件、主题、IM、知识库 |
不要把一个模式的服务端地址、Marketplace 配置或更新配置复制到另一个模式。构建模式和环境变量属于发布者配置；终端用户只需要按下载来源使用对应安装包。
升级前检查
升级前保留这些证据
- 项目目录已有 Git 提交、压缩归档或其它可恢复副本。
- 没有仍在运行的任务、批量任务或知识库后台加工。
- 重要会话已经等待写入完成，未处于持续重试或等待权限状态。
- 如果使用 IM、Webhook 或自动化，已经记录当前开关、渠道和任务状态。
- 凭证由系统或 Astravia 配置存储保护，不把
models.json、Token 或 Cookie 复制到备份说明中。
安装新版本通常会保留本地配置和数据目录。升级后若出现模型、插件或运行时异常，先在设置中重新验证对应能力，再查看配置与数据路径和故障排查；不要先删除整个 ~/.astravia 目录。
迁移哪些内容
| 内容 | 迁移建议 | 注意事项 |
|---|---|---|
| 项目文件 | 使用 Git、项目导出或文件系统备份 | 这是任务真实产物的首要副本 |
项目级 .astravia/ | 与项目一起迁移 | 保留目录结构，确认其中没有凭证 |
| 普通会话 | 迁移对应会话目录及元数据 | 不要让两个进程同时写同一会话 |
| 模型、MCP 和其它设置 | 优先通过设置页重新配置 | 手工迁移前脱敏，并核对版本兼容性 |
| 凭证与 OAuth 状态 | 不复制到公开或跨设备文档 | 按目标设备重新登录或重新授权 |
| 知识库原始资料 | 备份原始文件 | 整理结果可重新生成，不等同于原始资料 |
| IM 绑定状态 | 按渠道重新绑定更安全 | QR 绑定和第三方会话有自己的生命周期 |
全局路径、项目路径和会话目录见配置与数据路径。路径是当前实现事实，不应被当成跨版本稳定协议；自动化集成请优先使用 SDK、RPC 或公开 CLI。
升级后的验收
- 启动 Astravia，确认能打开一个已知项目。
- 显式选择一个模型，发送最小测试消息。
- 打开一个历史会话，确认消息和产物可读取。
- 如果使用插件、MCP、知识库或自动化，逐项执行一次只读或测试操作。
- 确认更新后的版本、权限和数据边界符合预期，再恢复无人值守任务。