ai-workspace-lab/xworkspace-console
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(setup): complete optional-parameters manual for curl|bash bootstrap

Browse Source 
Expand the all-in-one setup guide (zh+en) into a full reference of the
bootstrap script's supported options, grouped by purpose: subcommands
(uninstall/--purge), public-exposure & security, unified auth-token chain,
runtime modes, offline package, performance/locks, source/version overrides.
Fix the inaccurate TOKEN var -> AI_WORKSPACE_AUTH_TOKEN (the real precedence
chain). Sourced from scripts/setup-ai-workspace-all-in-one.sh.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Haitao Pan 2026-06-24 11:26:01 +08:00
parent b2c8c5d875
commit e74f2334e3
2 changed files with 160 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
docs/en/SETUP_AI_WORKSPACE_ALL_IN_ONE.md
View File

@ -27,26 +27,89 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/
GATEWAY_OPENCLAW_PUBLIC_ACCESS=false \ GATEWAY_OPENCLAW_PUBLIC_ACCESS=false \
VAULT_PUBLIC_ACCESS=false \ VAULT_PUBLIC_ACCESS=false \
LITELLM_API_CADDY_STRICT_WHITELIST=true \ LITELLM_API_CADDY_STRICT_WHITELIST=true \
TOKEN="your-unified-auth-token" \ AI_WORKSPACE_AUTH_TOKEN="your-unified-auth-token" \
bash - 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>`).
| 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` | `strict` for public/semi-public hosts (locks down public web APIs). |
| `AI_WORKSPACE_SECURITY_LEVEL` | standard | Use `strict` for public or semi-public hosts. | | `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | `false` | Expose Bridge via Caddy (typically the only public service on a public-IP host). |
| `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | false | Enable only when the Bridge domain should be reachable from the Internet. | | `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | `false` | Expose Portal/Console. Local-only (`127.0.0.1:17000`) by default is safer. |
| `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | false | Enable only when the Portal must be public. Local-only is safer. | | `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | `false` | Expose the OpenClaw gateway. |
| `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | false | Keep false unless OpenClaw must be exposed directly. | | `VAULT_PUBLIC_ACCESS` | `false` | Keep false for normal deployments. |
| `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_API_CADDY_STRICT_WHITELIST` | false | Enable with strict deployments when LiteLLM is exposed through Caddy. | | `LITELLM_CADDY_CONFIG_ENABLED` | deployment-dependent | Whether to render a Caddy site for LiteLLM. |
| `XWORKSPACE_CONSOLE_ENABLE_XRDP` | false | Enable only when remote desktop access is required. | | `XWORKSPACE_CONSOLE_ENABLE_XRDP` | `false` | Install XRDP remote desktop (only if graphical remote needed). |
| `XWORKMATE_BRIDGE_DOMAIN` | host-specific | Set the public Bridge domain, for example `acp-bridge.onwalk.net`. | | `XWORKMATE_BRIDGE_DOMAIN` | host-specific | Public Bridge domain, e.g. `acp-bridge.onwalk.net`. |
| `AI_WORKSPACE_OFFLINE_PACKAGE` | none | Use a pre-downloaded offline package for installation (e.g., `/path/to/offline.tar.gz`). |
## 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/<file>` → 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: For the current ACP Bridge host:
@ -58,7 +121,7 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/
bash - 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: 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. 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: On macOS, the script defaults to local validation mode and starts the Portal at:

97
docs/zh/SETUP_AI_WORKSPACE_ALL_IN_ONE.md
View File

@ -27,26 +27,91 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/
GATEWAY_OPENCLAW_PUBLIC_ACCESS=false \ GATEWAY_OPENCLAW_PUBLIC_ACCESS=false \
VAULT_PUBLIC_ACCESS=false \ VAULT_PUBLIC_ACCESS=false \
LITELLM_API_CADDY_STRICT_WHITELIST=true \ LITELLM_API_CADDY_STRICT_WHITELIST=true \
TOKEN="your-unified-auth-token" \ AI_WORKSPACE_AUTH_TOKEN="your-unified-auth-token" \
bash - 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`（收紧公开 Web API）。 |
| `AI_WORKSPACE_SECURITY_LEVEL` | standard | 公网或半公网主机使用 `strict`。 | | `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | `false` | Bridge 经 Caddy 对外（公网 IP 主机的典型唯一对外服务）。 |
| `XWORKMATE_BRIDGE_PUBLIC_ACCESS` | false | 仅当 Bridge 域名需要从互联网访问时启用。 | | `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | `false` | Portal/Console 对外。默认本地only（`127.0.0.1:17000`）更安全。 |
| `XWORKSPACE_CONSOLE_PUBLIC_ACCESS` | false | 仅当 Portal 必须公开时启用。仅限本地访问更安全。 | | `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | `false` | OpenClaw 网关对外。 |
| `GATEWAY_OPENCLAW_PUBLIC_ACCESS` | false | 除非 OpenClaw 必须直接暴露，否则保持为 false。 | | `VAULT_PUBLIC_ACCESS` | `false` | Vault 对外。常规部署保持 false。 |
| `VAULT_PUBLIC_ACCESS` | false | 常规部署保持为 false。 | | `LITELLM_API_CADDY_STRICT_WHITELIST` | `false` | strict 且 LiteLLM 经 Caddy 暴露时，限制公开网关路径白名单。 |
| `LITELLM_API_CADDY_STRICT_WHITELIST` | false | strict 部署且 LiteLLM 经 Caddy 暴露时启用。 | | `LITELLM_CADDY_CONFIG_ENABLED` | 视部署 | 是否为 LiteLLM 下发 Caddy 站点配置。 |
| `XWORKSPACE_CONSOLE_ENABLE_XRDP` | false | 仅当需要远程桌面访问时启用。 | | `XWORKSPACE_CONSOLE_ENABLE_XRDP` | `false` | 安装 XRDP 远程桌面（仅需要图形远程时）。 |
| `XWORKMATE_BRIDGE_DOMAIN` | 特定于主机 | 设置公开的 Bridge 域名，例如 `acp-bridge.onwalk.net`。 | | `XWORKMATE_BRIDGE_DOMAIN` | 主机相关 | 对外 Bridge 域名，例如 `acp-bridge.onwalk.net`。 |
| `AI_WORKSPACE_OFFLINE_PACKAGE` | 无 | 使用预下载的离线包进行安装（例如 `/path/to/offline.tar.gz`）。 |
## 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/<file>` → 否则 `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 主机： 对于当前 ACP Bridge 主机：
@ -58,7 +123,7 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/
bash - bash -
``` ```
## 5. 预期最终输出 ## 6. 预期最终输出
部署成功后，脚本会一次性打印部署的域名与 token，然后报告以下服务状态： 部署成功后，脚本会一次性打印部署的域名与 token，然后报告以下服务状态：
@ -73,7 +138,7 @@ curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/
请妥善保管 token。它不应该被复制到前端源代码或提交到 Git 中。 请妥善保管 token。它不应该被复制到前端源代码或提交到 Git 中。
## 6. 本地 macOS 验证 ## 7. 本地 macOS 验证
在 macOS 上，脚本默认进入本地验证模式并在以下地址启动 Portal： 在 macOS 上，脚本默认进入本地验证模式并在以下地址启动 Portal：