beaver_project/app-instance

app-instance

单实例应用单元：

• 一个 Docker 容器里同时运行前端、后端和 Nginx 反代
• 前端走 /
• 后端 API 走 /api
• WebSocket 走 /ws

关键文件

• Dockerfile
  • 统一镜像构建入口
• entrypoint.sh
  • 容器内启动前端、后端、Nginx
• create-instance.sh
  • 创建实例目录、生成配置、启动容器、写注册表
• remove-instance.sh
  • 删除容器、移除注册表、可选清理实例目录
• list-instances.sh
  • 查看当前注册实例
• instance-registry.py
  • 维护 runtime/registry/instances.json

注册表

默认注册表路径：

runtime/registry/instances.json

每条记录至少包含：

• instance_id
• instance_slug
• container_name
• host_port
• public_url
• instance_root
• image_name

常用命令

1. 构建镜像

docker build -t beaver/app-instance:latest .

2. 创建实例

./create-instance.sh \
  --image beaver/app-instance:latest \
  --instance-id demo-001 \
  --auth-username admin \
  --auth-password 123456 \
  --api-key 'your-api-key'

可选参数：

• --host-port
• --public-url
• --username
• --email
• --instance-host
• --authz-base-url
• --backend-id
• --client-id
• --client-secret
• --network
• --host-bind-ip
• --initial-skills-dir
• --skip-initial-skills
• --build
• --replace

3. 查看实例

./list-instances.sh
./list-instances.sh --json

4. 删除实例

./remove-instance.sh --instance-id demo-001

如果要把实例目录也一并清掉：

./remove-instance.sh --instance-id demo-001 --purge-data

目录约定

默认实例数据目录：

runtime/instances/<instance-slug>/

其中会生成：

runtime/instances/<instance-slug>/
└── beaver-home
    ├── config.json
    ├── web_auth_users.json
    └── workspace/

这个目录是单用户 sandbox 的配置与数据边界。容器内会把它挂到：

/root/.beaver/

并设置：

BEAVER_CONFIG_PATH=/root/.beaver/config.json
BEAVER_WORKSPACE=/root/.beaver/workspace

所以模型 provider/api_key/api_base/model 配一次即可，Web / channel 请求不需要、也不应该携带 API Key。

create-instance.sh 默认会把仓库根目录的 skills/ 非覆盖式复制到实例 workspace，并把同一个目录只读挂载到实例容器的 /opt/app/initial-skills。entrypoint.sh 每次启动都会用该目录补齐缺失的 published 初始 skills；已有 skill 目录不会被覆盖，index 只做并集追加。

当前状态

这层已经支持：

• 统一镜像构建
• 镜像内安装并启动新的 beaver 后端
• 实例创建
• 实例删除
• 实例列表
• 基于注册表的端口分配
• 为 deploy-control / router-proxy 记录用户名和实例 host

生产注意

• 实例容器的宿主机端口默认只绑定 127.0.0.1
• 外部访问应统一走 router-proxy
• 如果你确实要把单个实例端口直接暴露到公网，再显式传 --host-bind-ip 0.0.0.0
• 使用共享 external-connector sidecar 时，每个实例容器都必须带自己的内部回调地址： EXTERNAL_CONNECTOR_CALLBACK_BASE_URL=http://<app-instance-container-name>:8080
• 通过 create-instance.sh --network <docker-network> 创建实例时，脚本会默认使用 http://<container-name>:8080 作为回调地址；生产部署也可以用 --external-connector-callback-base-url <url> 显式覆盖
• BEAVER_BRIDGE_BASE_URL 只作为 sidecar 的旧连接或兜底地址；多实例部署不能依赖它路由所有入站事件

下一步可以继续接：

• portal 调用创建实例
• URL 分配和反向代理
• 实例续期 / 停用 / 启用