astrion-website/content/01-quick-start.md

快速上手

本章带你从零跑起 Astrion：克隆代码、完成初始化配置、启动服务，并根据你的使用场景选择正确的运行形态。

---

1. 系统要求

依赖	要求	说明
Python	3.9 及以上（推荐 3.11）	后端运行环境
Node.js	18 及以上	构建前端、使用 CLI
Docker	可选	仅 web/docker 模式需要，host 模式不需要
WSL2	仅 Windows	Windows 上使用宿主机沙箱的前置条件

macOS、Linux、Windows（WSL2）均可运行。三平台沙箱能力的差异见《核心概念》一章。

---

2. 安装

# 1. 克隆仓库
git clone https://github.com/JOJO6618/astrion.git
cd astrion

# 2. 初始化：创建 venv、安装依赖、运行交互式配置向导
#    向导会依次询问：运行模式 → 监听地址/端口 → 管理员账户 → 模型 API → 生成密钥
./setup.sh

# 3. 构建前端
npm install && npm run build

# 4.（仅 web/docker 模式）构建沙箱镜像，见下文「选择运行模式」
docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .

# 5. 启动
./start.sh
# 或者手动启动：
python -m server.app --port 8091 --thinking-mode

启动后访问 http://localhost:8091，用向导中设置的管理员账户登录。

setup.sh 向导会把配置写入仓库根目录的 .env。这是开发备用方式；生产部署建议改用「数据根目录下的 settings.json」或系统环境变量，见下文「配置优先级」。

---

3. 运行端口与监听地址

• 默认端口：8091（WEB_SERVER_PORT）。
• 监听地址（WEB_SERVER_HOST）：
  • 单机自用：建议 127.0.0.1，只监听本机回环，局域网不可达；
  • 多用户/服务器部署：用 0.0.0.0。
• 启动命令行参数 --port 可以临时覆盖配置。
• 调试模式 WEB_SERVER_DEBUG=1（同时开启 Flask reloader），生产环境保持 0。

---

4. 数据路径：数据都存在哪、怎么搬迁

Astrion 的运行态数据（对话记录、用户、日志、部署级配置）默认全部放在用户主目录下，不污染源码树：

~/.astrion/astrion/           ← 数据根目录（data_root）
├── settings.json             ← 唯一配置文件（优先级最高）
├── config/                   ← 部署级配置（模型库等，host/web 共享）
├── host/                     ← host 模式的数据
│   ├── data/  users/  logs/  api/
└── web/                      ← web/docker 模式的数据（结构同上）

按运行模式自动分流：TERMINAL_SANDBOX_MODE=host 时数据进 host/，否则进 web/。

路径相关环境变量（优先级从高到低）

环境变量	作用
DATA_DIR / LOGS_DIR / USER_SPACE_DIR / API_USER_SPACE_DIR	单独覆盖某一个目录（最高优先级）
ASTRION_DATA_ROOT	整体搬迁数据根目录（默认 ~/.astrion/astrion）
DEPLOY_CONFIG_DIR	单独搬迁部署级配置目录（默认 <数据根>/config/）

具体目录变量支持相对路径（相对仓库根目录展开）、绝对路径与 ~。

配置优先级

同名配置生效顺序：<数据根>/settings.json ＞ 系统环境变量 ＞ 仓库根目录 .env ＞ 代码默认值。

.env 加载时不覆盖已存在的系统环境变量；settings.json 是推荐的生产配置方式，例如：

{
  "server": { "port": 8091, "host": "127.0.0.1" }
}

---

5. 配置主智能体模型

主智能体的模型统一在 custom_models.json 中注册。

放置位置（按回退链查找，找到即止）：

1. <数据根>/config/custom_models.json（生产推荐）
2. 仓库内 config/custom_models.json
3. 仓库内 config/custom_models.json.example（种子示例）

完整字段说明：

{
  "models": [
    {
      "model_name": "Kimi-K3",
      "description": "展示给用户的模型描述",
      "visible": true,
      "url": "${API_BASE_KIMI}",
      "apikey": "${API_KEY_KIMI}",
      "multimodal": "image,video",
      "reasoning_capability": "fast,thinking",
      "reasoning_effort": true,
      "context_window": 1048576,
      "max_output_tokens": 64000,
      "thinkmode_status": {
        "type": "param_toggle",
        "model_id": "k3",
        "fast_extra_parameter":     { "thinking": { "type": "disabled" } },
        "thinking_extra_parameter": { "thinking": { "effort": "max" } }
      },
      "extra_parameter": {},
      "model_description": "注入系统提示词的模型自我描述"
    }
  ]
}

字段	必填	说明
model_name	✅	模型条目名，UI 中显示，也是各配置引用它的 key
url	✅	API 基础地址。支持 ${环境变量} 引用，密钥不要写明文
apikey	✅	API Key，同样支持 ${...}
description		列表中展示的说明文字
visible		是否在模型选择菜单中可见
multimodal		image,video 等；决定输入栏是否允许发图/视频
reasoning_capability		fast,thinking；决定思考模式可选项
reasoning_effort		是否支持「推理强度」滑块
context_window		上下文窗口大小（token），压缩阈值、用量统计以此为基准
max_output_tokens		单次最大输出 token
thinkmode_status		param_toggle 类型：model_id 为真实模型 ID；fast/thinking_extra_parameter 为两种模式下分别附加的请求参数
extra_parameter		所有请求都附加的额外参数
model_description		注入系统提示词的自我介绍

最小配置只需要 4 个字段：model_name / url / apikey / thinkmode_status.model_id，其余字段均有默认值。

提醒：setup.sh 向导在第 5 步创建的模型条目就是最小配置——multimodal 为 none（不能发图/视频）、context_window 固定 128000、max_output_tokens 32768。如果你的模型支持多模态或更大上下文，配完向导后请手动编辑 <数据根>/config/custom_models.json 补齐字段。

默认模型：不设 AGENT_DEFAULT_MODEL 时使用列表中第一个可见模型；也可以在个人空间「模型与思考」页设置每用户默认模型。

注意：旧版的 AGENT_API_* / AGENT_THINKING_* / AGENT_TITLE_* 环境变量已从代码中移除，配置它们不再有任何效果。

---

6. 配置子智能体模型

子智能体（含三个审核智能体）使用独立的模型库：sub_agent_models.json。

放置位置：仅从部署配置目录读取——<数据根>/config/sub_agent_models.json（可用 SUB_AGENT_MODELS_CONFIG_FILE 单独覆盖）。没有这个文件，子智能体将无法启动，会直接报「未找到可用子智能体模型配置」。

结构：

{
  "default_model": "deepseek-v4-flash",
  "models": [
    {
      "name": "deepseek-v4-flash",
      "url": "${SUB_AGENT_API_BASE}",
      "apikey": "${SUB_AGENT_API_KEY}",
      "model_id": "deepseek-v4-flash",
      "modes": "fast,thinking",
      "multimodal": "image",
      "max_output": 32000,
      "max_context": 128000,
      "extra_parameter": {},
      "fast_extra_parameter": {},
      "thinking_extra_parameter": {}
    }
  ]
}

要点：

• default_model：默认条目名；子智能体/审核智能体配置里 model 留空时用它。若指定的名字不存在，回退到列表中第一个可用条目。
• 字段名做了宽松兼容：name/model_name/model、url/base_url、apikey/api_key 均可；modes 写 fast,thinking 表示支持思考模式，只写 fast 表示纯快速模式。
• 也支持与主模型库相同的 thinkmode_status 结构，可以直接从 custom_models.json 复制条目改名字用。
• url / apikey 同样支持 ${环境变量} 引用。

子智能体相关环境变量：

变量	默认	说明
SUB_AGENT_MAX_ACTIVE	5	同时运行的子智能体上限
SUB_AGENT_DEFAULT_TIMEOUT	180（秒）	默认超时
SUB_AGENT_TASKS_BASE_DIR	<数据根>/<模式>/data/sub_agent_tasks	任务目录
SUB_AGENT_PROJECT_RESULTS_DIR	<工作区>/sub_agent_results	交付目录（有意放在工作区内）

---

7. 选择运行模式：host 还是 docker（web）

由 TERMINAL_SANDBOX_MODE 决定，两种模式面向完全不同的场景：

	host 模式	web/docker 模式
定位	本地个人使用	服务器多用户部署
命令执行	宿主机 OS 沙箱（macOS sandbox-exec / Linux bwrap / Windows WSL2）	每个用户独立 Docker 容器，受限档权限下以非特权 uid 执行
数据目录	~/.astrion/astrion/host/	~/.astrion/astrion/web/
前置准备	无需镜像；Windows 需先装 WSL2	必须先构建镜像：docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .（构建上下文必须是仓库根）
镜像名	—	由 TERMINAL_SANDBOX_IMAGE 指定，建议 my-agent-shell:latest

选择建议：

• 一个人在自己电脑上用 → host。文件管理器、本地工具链直接可用，体验最好。
• 部署到服务器给多人用 → docker。容器天然隔离用户之间的文件与进程。
• host 模式可以同时读取 web 模式的数据（用户列表、工作区合并显示），反向不行。

沙箱镜像基于 python:3.11-slim，内置 LibreOffice / Pandoc / FFmpeg / Tesseract OCR（含中文）/ Chromium / Node 20 / docx / pptxgenjs 等常用工具链。程序不会自动构建镜像，web 模式启动前必须手动构建一次。

---

8. 首次启动检查清单

1. 浏览器打开 http://localhost:8091，用管理员账户登录；
2. 进入个人空间，确认「模型与思考」页能看到你配置的模型；
3. 随便发一条消息，确认主智能体能正常回复；
4. 让主智能体创建一个子智能体（或直接说「帮我查一下 xxx」触发），确认 sub_agent_models.json 配置正确；
5. 若是 web 模式，确认镜像已构建、终端容器能正常拉起。

到这里，你的 Astrion 已经可以正常工作了。接下来建议阅读《核心概念》，理解部署模式、权限模式、执行环境、运行模式这四组概念——它们决定了 Astrion 的行为边界。