diff --git a/docs/en/SETUP_AI_WORKSPACE_ALL_IN_ONE.md b/docs/en/SETUP_AI_WORKSPACE_ALL_IN_ONE.md index 627b49c..5986b0d 100644 --- a/docs/en/SETUP_AI_WORKSPACE_ALL_IN_ONE.md +++ b/docs/en/SETUP_AI_WORKSPACE_ALL_IN_ONE.md @@ -27,26 +27,89 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/ GATEWAY_OPENCLAW_PUBLIC_ACCESS=false \ VAULT_PUBLIC_ACCESS=false \ LITELLM_API_CADDY_STRICT_WHITELIST=true \ - TOKEN="your-unified-auth-token" \ + AI_WORKSPACE_AUTH_TOKEN="your-unified-auth-token" \ bash - ``` -## 3. Recommended Parameters +> Subcommands are passed as positional args to `bash -`: `... | bash -s -- uninstall`. -| Variable | Default | Recommended Use | +## 3. Subcommands + +Passed as the first positional arg (`... | bash -s -- `). + +| Subcommand | Effect | +| --- | --- | +| `uninstall` | Stop & remove all AI Workspace apps/services (macOS launchd; Linux systemd units + docker containers). Config, tokens and data under `$HOME` are **kept**. | +| `uninstall --purge` | Same teardown, then **delete** config/state/token/cache dirs (`~/.config/xworkspace`, `~/.local/state/xworkspace`, `~/.openclaw`, `~/.ai_workspace_auth_token`, `/tmp/ai-workspace-deploy`; plus `/opt/ai-workspace` & `/etc/ai-workspace` on Linux as root). Prints a plan first, reports each path removed/absent. | + +## 4. Optional Parameters (Environment Variables) + +Pass before `bash -`. Full set of supported options, grouped by purpose. + +### 4.1 Public Exposure & Security + +| Variable | Default | Notes | | --- | --- | --- | -| `TOKEN` | generated or reused | Sets one unified auth token for Bridge, Portal, LiteLLM, OpenClaw, and Vault. | -| `AI_WORKSPACE_SECURITY_LEVEL` | standard | Use `strict` for public or semi-public hosts. | -| `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | false | Enable only when the Bridge domain should be reachable from the Internet. | -| `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | false | Enable only when the Portal must be public. Local-only is safer. | -| `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | false | Keep false unless OpenClaw must be exposed directly. | -| `VAULT_PUBLIC_ACCESS` | false | Keep false for normal deployments. | -| `LITELLM_API_CADDY_STRICT_WHITELIST` | false | Enable with strict deployments when LiteLLM is exposed through Caddy. | -| `XWORKSPACE_CONSOLE_ENABLE_XRDP` | false | Enable only when remote desktop access is required. | -| `XWORKMATE_BRIDGE_DOMAIN` | host-specific | Set the public Bridge domain, for example `acp-bridge.onwalk.net`. | -| `AI_WORKSPACE_OFFLINE_PACKAGE` | none | Use a pre-downloaded offline package for installation (e.g., `/path/to/offline.tar.gz`). | +| `AI_WORKSPACE_SECURITY_LEVEL` | `standard` | `strict` for public/semi-public hosts (locks down public web APIs). | +| `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | `false` | Expose Bridge via Caddy (typically the only public service on a public-IP host). | +| `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | `false` | Expose Portal/Console. Local-only (`127.0.0.1:17000`) by default is safer. | +| `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | `false` | Expose the OpenClaw gateway. | +| `VAULT_PUBLIC_ACCESS` | `false` | Keep false for normal deployments. | +| `LITELLM_API_CADDY_STRICT_WHITELIST` | `false` | With strict + LiteLLM behind Caddy, restrict the public gateway path whitelist. | +| `LITELLM_CADDY_CONFIG_ENABLED` | deployment-dependent | Whether to render a Caddy site for LiteLLM. | +| `XWORKSPACE_CONSOLE_ENABLE_XRDP` | `false` | Install XRDP remote desktop (only if graphical remote needed). | +| `XWORKMATE_BRIDGE_DOMAIN` | host-specific | Public Bridge domain, e.g. `acp-bridge.onwalk.net`. | -## 4. Target Host Example +### 4.2 Unified Auth Token + +First non-empty of: `AI_WORKSPACE_AUTH_TOKEN` → `XWORKSPACE_CONSOLE_AUTH_TOKEN` → `XWORKMATE_BRIDGE_AUTH_TOKEN` → `BRIDGE_AUTH_TOKEN` → `INTERNAL_SERVICE_TOKEN` → `DEPLOY_TOKEN` is used as the unified token (Bridge / LiteLLM / OpenClaw / Vault). If all unset it is **auto-generated** into `AI_WORKSPACE_AUTH_TOKEN_FILE` (default `~/.ai_workspace_auth_token`). The Vault root token can be set separately via `VAULT_SERVER_ROOT_ACCESS_TOKEN`. + +### 4.3 Runtime Modes + +| Variable | Default | Notes | +| --- | --- | --- | +| `AI_WORKSPACE_RUNTIME_MODES` | `docker,systemd` | Runtime modes; `docker` and `k3s` are mutually exclusive. | +| `POSTGRESQL_DEPLOY_MODE` | `compose` | `native` for apt/systemd. | + +### 4.4 Offline Package (acceleration / air-gap) + +| Variable | Default | Notes | +| --- | --- | --- | +| `AI_WORKSPACE_OFFLINE_MODE` | `auto` | `auto` (try offline, fall back online) / `force` / `off`. | +| `AI_WORKSPACE_OFFLINE_PACKAGE` | none | Local package file/dir or URL. | +| `AI_WORKSPACE_OFFLINE_PACKAGE_URL` | none | Direct tarball URL. | +| `AI_WORKSPACE_OFFLINE_PACKAGE_BASE_URL` | none | Mirror dir containing the target tarball; empty skips the mirror. | +| `AI_WORKSPACE_OFFLINE_RELEASE_TAG` | `latest` | GitHub Release tag or `latest`. | +| `AI_WORKSPACE_OFFLINE_REPO` | `ai-workspace-lab/xworkspace-console` | Repo hosting offline packages. | +| `AI_WORKSPACE_OFFLINE_AUTO_DOWNLOAD` | `true` | In auto mode, fetch the matching package from GitHub Releases (reassembles split parts). | +| `AI_WORKSPACE_OFFLINE_WORK_DIR` | `/tmp/ai-workspace-offline` | Extraction work dir. | + +> Source priority: `OFFLINE_PACKAGE` → `OFFLINE_PACKAGE_URL` → `OFFLINE_PACKAGE_BASE_URL/` → else `AUTO_DOWNLOAD` via GitHub Releases. On failure falls back online per-OS (apt/yum or macOS homebrew + git clone + online runtime fetch). + +### 4.5 Performance / Concurrency / Locks + +| Variable | Default | Notes | +| --- | --- | --- | +| `AI_WORKSPACE_PREFETCH_ENABLED` | `true` | Prefetch repos/components. | +| `AI_WORKSPACE_PREFETCH_DIR` | `/var/tmp/ai-workspace-prefetch` | Prefetch dir. | +| `AI_WORKSPACE_MAX_PARALLEL_JOBS` | `auto` | Concurrency cap (never exceeds 2× online CPU cores). | +| `AI_WORKSPACE_SPLIT_PHASES` | `true` | Phased execution. | +| `AI_WORKSPACE_RUNTIME_PREBUILD_ENABLED` | `false` | Prebuild runtime. | +| `AI_WORKSPACE_DEPLOYMENT_LOCK_TIMEOUT` | `1800` | Deployment mutex wait (s). | +| `AI_WORKSPACE_APT_LOCK_TIMEOUT` | `900` | Wait for dpkg/apt lock (s) (avoids racing cloud-init/unattended-upgrades). | + +### 4.6 Source/Version Overrides (dev & offline customization) + +| Variable | Notes | +| --- | --- | +| `PLAYBOOK_DIR` | Local playbooks checkout (handy for macOS validation). | +| `XWORKSPACE_CONSOLE_DIR` | Local xworkspace-console checkout (macOS). | +| `XWORKSPACE_CONSOLE_SOURCE_REPO` / `XWORKSPACE_CONSOLE_SOURCE_VERSION` | Git source/version for the Linux console playbook. | +| `XWORKSPACE_CONSOLE_RUNTIME_ARCHIVE` / `QMD_RUNTIME_ARCHIVE` | Prebuilt runtime tar paths (offline). | +| `LITELLM_PACKAGE_SPEC` / `AI_WORKSPACE_PREBUILT_COMPONENTS_REQUIRED` | LiteLLM package spec / require prebuilt components. | +| `OPENCLAW_MULTI_SESSION_PLUGIN_PACKAGE_SPEC` / `OPENCLAW_MULTI_SESSION_PLUGIN_DIR` | OpenClaw plugin source / local checkout (macOS link install). | + +## 5. Target Host Example For the current ACP Bridge host: @@ -58,7 +121,7 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/ bash - ``` -## 5. Expected Final Output +## 6. Expected Final Output After a successful deployment, the script prints the deployed domain and token once, then reports service status for: @@ -73,7 +136,7 @@ After a successful deployment, the script prints the deployed domain and token o Keep the token output private. It should not be copied into frontend source code or committed to Git. -## 6. Local macOS Validation +## 7. Local macOS Validation On macOS, the script defaults to local validation mode and starts the Portal at: diff --git a/docs/zh/SETUP_AI_WORKSPACE_ALL_IN_ONE.md b/docs/zh/SETUP_AI_WORKSPACE_ALL_IN_ONE.md index e99cac1..141a33f 100644 --- a/docs/zh/SETUP_AI_WORKSPACE_ALL_IN_ONE.md +++ b/docs/zh/SETUP_AI_WORKSPACE_ALL_IN_ONE.md @@ -27,26 +27,91 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/ GATEWAY_OPENCLAW_PUBLIC_ACCESS=false \ VAULT_PUBLIC_ACCESS=false \ LITELLM_API_CADDY_STRICT_WHITELIST=true \ - TOKEN="your-unified-auth-token" \ + AI_WORKSPACE_AUTH_TOKEN="your-unified-auth-token" \ bash - ``` -## 3. 推荐参数 +> 子命令作为 `bash -` 的位置参数传入:`... | bash -s -- uninstall`。 -| 变量 | 默认值 | 推荐用法 | +## 3. 子命令 + +作为第一个位置参数传入(`... | bash -s -- <子命令>`)。 + +| 子命令 | 作用 | +| --- | --- | +| `uninstall` | 停止并移除所有 AI Workspace 应用/服务(macOS launchd;Linux systemd 单元 + docker 容器)。`$HOME` 下的配置、token、数据**保留**。 | +| `uninstall --purge` | 同上,并**删除**配置/状态/token/缓存目录(`~/.config/xworkspace`、`~/.local/state/xworkspace`、`~/.openclaw`、`~/.ai_workspace_auth_token`、`/tmp/ai-workspace-deploy`;Linux 有 root 时再加 `/opt/ai-workspace`、`/etc/ai-workspace`)。执行前打印清单,逐项报告 已删/不存在。 | + +## 4. 可选参数(环境变量) + +在 `bash -` 之前以环境变量传入。下表为脚本支持的完整可选项,按用途分类。 + +### 4.1 公网暴露与安全 + +| 变量 | 默认 | 说明 | | --- | --- | --- | -| `TOKEN` | 生成或复用 | 为 Bridge、Portal、LiteLLM、OpenClaw 和 Vault 设置统一认证 token。 | -| `AI_WORKSPACE_SECURITY_LEVEL` | standard | 公网或半公网主机使用 `strict`。 | -| `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | false | 仅当 Bridge 域名需要从互联网访问时启用。 | -| `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | false | 仅当 Portal 必须公开时启用。仅限本地访问更安全。 | -| `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | false | 除非 OpenClaw 必须直接暴露,否则保持为 false。 | -| `VAULT_PUBLIC_ACCESS` | false | 常规部署保持为 false。 | -| `LITELLM_API_CADDY_STRICT_WHITELIST` | false | strict 部署且 LiteLLM 经 Caddy 暴露时启用。 | -| `XWORKSPACE_CONSOLE_ENABLE_XRDP` | false | 仅当需要远程桌面访问时启用。 | -| `XWORKMATE_BRIDGE_DOMAIN` | 特定于主机 | 设置公开的 Bridge 域名,例如 `acp-bridge.onwalk.net`。 | -| `AI_WORKSPACE_OFFLINE_PACKAGE` | 无 | 使用预下载的离线包进行安装(例如 `/path/to/offline.tar.gz`)。 | +| `AI_WORKSPACE_SECURITY_LEVEL` | `standard` | 公网/半公网主机用 `strict`(收紧公开 Web API)。 | +| `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | `false` | Bridge 经 Caddy 对外(公网 IP 主机的典型唯一对外服务)。 | +| `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | `false` | Portal/Console 对外。默认本地only(`127.0.0.1:17000`)更安全。 | +| `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | `false` | OpenClaw 网关对外。 | +| `VAULT_PUBLIC_ACCESS` | `false` | Vault 对外。常规部署保持 false。 | +| `LITELLM_API_CADDY_STRICT_WHITELIST` | `false` | strict 且 LiteLLM 经 Caddy 暴露时,限制公开网关路径白名单。 | +| `LITELLM_CADDY_CONFIG_ENABLED` | 视部署 | 是否为 LiteLLM 下发 Caddy 站点配置。 | +| `XWORKSPACE_CONSOLE_ENABLE_XRDP` | `false` | 安装 XRDP 远程桌面(仅需要图形远程时)。 | +| `XWORKMATE_BRIDGE_DOMAIN` | 主机相关 | 对外 Bridge 域名,例如 `acp-bridge.onwalk.net`。 | -## 4. 目标主机示例 +### 4.2 统一认证 Token + +按以下顺序取第一个非空值作为统一 token(传给 Bridge / LiteLLM / OpenClaw / Vault): +`AI_WORKSPACE_AUTH_TOKEN` → `XWORKSPACE_CONSOLE_AUTH_TOKEN` → `XWORKMATE_BRIDGE_AUTH_TOKEN` → `BRIDGE_AUTH_TOKEN` → `INTERNAL_SERVICE_TOKEN` → `DEPLOY_TOKEN`。 +均未设则**自动生成**并存入 `AI_WORKSPACE_AUTH_TOKEN_FILE`(默认 `~/.ai_workspace_auth_token`)。Vault root token 可用 `VAULT_SERVER_ROOT_ACCESS_TOKEN` 单独指定。 + +### 4.3 运行时形态 + +| 变量 | 默认 | 说明 | +| --- | --- | --- | +| `AI_WORKSPACE_RUNTIME_MODES` | `docker,systemd` | 运行时形态组合;`docker` 与 `k3s` 互斥。 | +| `POSTGRESQL_DEPLOY_MODE` | `compose` | `native` 走 apt/systemd。 | + +### 4.4 离线包(加速 / 气隙) + +| 变量 | 默认 | 说明 | +| --- | --- | --- | +| `AI_WORKSPACE_OFFLINE_MODE` | `auto` | `auto`(尝试离线、失败回退在线)/ `force`(强制离线)/ `off`。 | +| `AI_WORKSPACE_OFFLINE_PACKAGE` | 无 | 本地离线包文件/目录或 URL。 | +| `AI_WORKSPACE_OFFLINE_PACKAGE_URL` | 无 | 直链 tar URL。 | +| `AI_WORKSPACE_OFFLINE_PACKAGE_BASE_URL` | 无 | 镜像目录(其下含目标 tar);为空则跳过镜像。 | +| `AI_WORKSPACE_OFFLINE_RELEASE_TAG` | `latest` | GitHub Release tag 或 `latest`。 | +| `AI_WORKSPACE_OFFLINE_REPO` | `ai-workspace-lab/xworkspace-console` | 离线包所在仓库。 | +| `AI_WORKSPACE_OFFLINE_AUTO_DOWNLOAD` | `true` | auto 模式下从 GitHub Release 自动取匹配包(含分片重组)。 | +| `AI_WORKSPACE_OFFLINE_WORK_DIR` | `/tmp/ai-workspace-offline` | 离线包解压工作目录。 | + +> 取数优先级:`OFFLINE_PACKAGE` → `OFFLINE_PACKAGE_URL` → `OFFLINE_PACKAGE_BASE_URL/` → 否则 `AUTO_DOWNLOAD` 走 GitHub Release。失败则按系统回退在线(apt/yum 或 macOS homebrew + git clone + 在线拉 runtime)。 + +### 4.5 性能 / 并发 / 锁 + +| 变量 | 默认 | 说明 | +| --- | --- | --- | +| `AI_WORKSPACE_PREFETCH_ENABLED` | `true` | 预取仓库/组件。 | +| `AI_WORKSPACE_PREFETCH_DIR` | `/var/tmp/ai-workspace-prefetch` | 预取目录。 | +| `AI_WORKSPACE_MAX_PARALLEL_JOBS` | `auto` | 并发上限(不超过 2× 在线 CPU 核数)。 | +| `AI_WORKSPACE_SPLIT_PHASES` | `true` | 分阶段执行。 | +| `AI_WORKSPACE_RUNTIME_PREBUILD_ENABLED` | `false` | 预构建 runtime。 | +| `AI_WORKSPACE_DEPLOYMENT_LOCK_TIMEOUT` | `1800` | 部署互斥锁等待秒数。 | +| `AI_WORKSPACE_APT_LOCK_TIMEOUT` | `900` | 等待 dpkg/apt 锁秒数(避开 cloud-init/unattended-upgrades 抢锁)。 | + +### 4.6 源/版本覆盖(开发与离线定制) + +| 变量 | 说明 | +| --- | --- | +| `PLAYBOOK_DIR` | 本地 playbooks 检出目录(macOS 验证常用)。 | +| `XWORKSPACE_CONSOLE_DIR` | 本地 xworkspace-console 检出(macOS)。 | +| `XWORKSPACE_CONSOLE_SOURCE_REPO` / `XWORKSPACE_CONSOLE_SOURCE_VERSION` | Linux console playbook 的 Git 源/版本。 | +| `XWORKSPACE_CONSOLE_RUNTIME_ARCHIVE` / `QMD_RUNTIME_ARCHIVE` | 预编译 runtime tar 路径(离线)。 | +| `LITELLM_PACKAGE_SPEC` / `AI_WORKSPACE_PREBUILT_COMPONENTS_REQUIRED` | LiteLLM 包规格 / 强制要求预编译组件。 | +| `OPENCLAW_MULTI_SESSION_PLUGIN_PACKAGE_SPEC` / `OPENCLAW_MULTI_SESSION_PLUGIN_DIR` | OpenClaw 多会话插件源 / 本地检出(macOS link 安装)。 | + +## 5. 目标主机示例 对于当前 ACP Bridge 主机: @@ -58,7 +123,7 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/ bash - ``` -## 5. 预期最终输出 +## 6. 预期最终输出 部署成功后,脚本会一次性打印部署的域名与 token,然后报告以下服务状态: @@ -73,7 +138,7 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/ 请妥善保管 token。它不应该被复制到前端源代码或提交到 Git 中。 -## 6. 本地 macOS 验证 +## 7. 本地 macOS 验证 在 macOS 上,脚本默认进入本地验证模式并在以下地址启动 Portal: