第一次提交

app-instance/README.md

@@ -0,0 +1,136 @@
+# 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`
+
+## 注册表
+
+默认注册表路径：
+
+```text
+runtime/registry/instances.json
+```
+
+每条记录至少包含：
+
+- `instance_id`
+- `instance_slug`
+- `container_name`
+- `host_port`
+- `public_url`
+- `instance_root`
+- `image_name`
+
+## 常用命令
+
+### 1. 构建镜像
+
+```bash
+docker build -t nano/app-instance:latest .
+```
+
+### 2. 创建实例
+
+```bash
+./create-instance.sh \
+  --image nano/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`
+- `--build`
+- `--replace`
+
+### 3. 查看实例
+
+```bash
+./list-instances.sh
+./list-instances.sh --json
+```
+
+### 4. 删除实例
+
+```bash
+./remove-instance.sh --instance-id demo-001
+```
+
+如果要把实例目录也一并清掉：
+
+```bash
+./remove-instance.sh --instance-id demo-001 --purge-data
+```
+
+## 目录约定
+
+默认实例数据目录：
+
+```text
+runtime/instances/<instance-slug>/
+```
+
+其中会生成：
+
+```text
+runtime/instances/<instance-slug>/
+└── nanobot-home
+    ├── config.json
+    ├── web_auth_users.json
+    └── workspace/
+```
+
+## 当前状态
+
+这层已经支持：
+
+- 统一镜像构建
+- 实例创建
+- 实例删除
+- 实例列表
+- 基于注册表的端口分配
+- 为 deploy-control / router-proxy 记录用户名和实例 host
+
+## 生产注意
+
+- 实例容器的宿主机端口默认只绑定 `127.0.0.1`
+- 外部访问应统一走 `router-proxy`
+- 如果你确实要把单个实例端口直接暴露到公网，再显式传 `--host-bind-ip 0.0.0.0`
+
+下一步可以继续接：
+
+- portal 调用创建实例
+- URL 分配和反向代理
+- 实例续期 / 停用 / 启用