mirror of
https://github.com/orbien-org/orbien.git
synced 2026-09-22 00:01:31 +00:00
docs: update docs
This commit is contained in:
lxien
@@ -65,6 +65,55 @@ services:
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<div id="env">
|
||||
|
||||
### 方式三：用环境变量注入配置
|
||||
|
||||
</div>
|
||||
|
||||
配置里写 <code>{'{{env.NAME}}'}</code>，用 `-e` 或 Compose `environment` 传入。语法见 [环境变量](./features/env.md)。
|
||||
|
||||
```toml
|
||||
#orbien-server.toml
|
||||
listen = "{{env.ORBIEN_LISTEN:0.0.0.0:9527}}"
|
||||
|
||||
[auth]
|
||||
token = "{{env.ORBIEN_TOKEN}}"
|
||||
|
||||
[dashboard]
|
||||
addr = "0.0.0.0"
|
||||
port = 8020
|
||||
user = "{{env.DASHBOARD_USER:admin}}"
|
||||
password = "{{env.DASHBOARD_PASSWORD:123456}}"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yaml
|
||||
services:
|
||||
orbien-server:
|
||||
image: ghcr.io/orbien-org/orbien-server:latest
|
||||
container_name: orbien-server
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "9527:9527"
|
||||
- "8020:8020"
|
||||
environment:
|
||||
ORBIEN_TOKEN: ${ORBIEN_TOKEN}
|
||||
DASHBOARD_PASSWORD: ${DASHBOARD_PASSWORD}
|
||||
volumes:
|
||||
- ./orbien-server.toml:/etc/orbien/orbien-server.toml:ro
|
||||
```
|
||||
|
||||
```shell
|
||||
export ORBIEN_TOKEN=YOUR_TOKEN
|
||||
export DASHBOARD_PASSWORD=change-me
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
:::warning
|
||||
字符串字段必须给占位符加引号；变量未设置且没有默认值时进程会启动失败。桌面客户端不要在配置里写 <code>{'{{env.}}'}</code>。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 客户端
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"label": "功能",
|
||||
"label": "功能特性",
|
||||
"position": 12
|
||||
}
|
||||
|
||||
@@ -8,7 +8,11 @@ title: 身份认证
|
||||
|
||||
客户端连接服务端时的 Token 鉴权。服务端未配置 `token`（或为空）时不校验。
|
||||
|
||||
两端 `token` 必须一致，否则登录失败（`authorization failed`）。
|
||||
服务端开启鉴权后，两端 `token` 必须一致，否则登录失败。Token 从配置文件读取，也可用环境变量注入，见 [环境变量](./env.md)。
|
||||
|
||||
:::tip
|
||||
登录时用 token 计算摘要，不会把 token 明文发给服务端!
|
||||
:::
|
||||
|
||||
## 示例
|
||||
|
||||
@@ -33,15 +37,3 @@ token = "YOUR_TOKEN"
|
||||
| 参数 | 必填 | 默认值 | 说明 |
|
||||
|--------------|----|-----|------------------------|
|
||||
| `auth.token` | 否 | | 共享密钥；服务端为空表示关闭鉴权；两端需一致 |
|
||||
|
||||
## 命令行
|
||||
|
||||
服务端也可通过参数设置（会覆盖配置文件中的 `token`）：
|
||||
|
||||
```shell
|
||||
./orbien-server -c orbien-server.toml -t YOUR_TOKEN
|
||||
```
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------------------|-----|------|
|
||||
| `-t` / `--token` | | 共享密钥 |
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
sidebar_label: 环境变量
|
||||
title: 环境变量
|
||||
---
|
||||
|
||||
# 环境变量
|
||||
|
||||
配置文件可用 `{{env.NAME}}` 引用进程环境变量，**Docker**、**systemd**、**K8s** 等凡能注入环境变量的场景都适用。
|
||||
|
||||
:::warning
|
||||
**GUI**客户端（`Orbien-Desktop`）不支持该语法，请在界面里填写实际值，不要填写表达式！
|
||||
:::
|
||||
|
||||
## 语法
|
||||
|
||||
```toml
|
||||
[auth]
|
||||
token = "{{env.ORBIEN_TOKEN}}"
|
||||
|
||||
[[tunnels]]
|
||||
name = "ssh"
|
||||
protocol = "tcp"
|
||||
service = "127.0.0.1:22"
|
||||
remotePort = {{ env.SSH_REMOTE_PORT:9000 } }
|
||||
```
|
||||
|
||||
| 写法 | 含义 |
|
||||
|---------------------------------------|------------------|
|
||||
| <code>{'{{env.NAME}}'}</code> | 必填。变量未设置或为空时启动失败 |
|
||||
| <code>{'{{env.NAME:default}}'}</code> | 可选。未设置或为空时使用默认值 |
|
||||
| <code>{'"{{env.NAME}}"'}</code> | 字符串字段，占位符必须放在引号内 |
|
||||
| <code>{'{{env.NAME}}'}</code> | 数字、布尔字段，不要加引号 |
|
||||
|
||||
变量名只能包含字母、数字、下划线，且不能以数字开头。花括号内空白可有可无：<code>{'{{ env.NAME }}'}</code> 合法。
|
||||
|
||||
第一个 `:` 才是默认值分隔符，因此地址类默认值可以直接写：
|
||||
|
||||
```toml
|
||||
listen = "{{env.ORBIEN_LISTEN:0.0.0.0:9527}}"
|
||||
server = "{{env.ORBIEN_SERVER:127.0.0.1:9527}}"
|
||||
```
|
||||
|
||||
密钥建议用必填写法 <code>{'{{env.ORBIEN_TOKEN}}'}</code>，不要给 token 写一个可猜测的默认值。
|
||||
|
||||
@@ -15,9 +15,9 @@
|
||||
"message": "Transport Protocols",
|
||||
"description": "The label for category '传输协议' in sidebar 'docsSidebar'"
|
||||
},
|
||||
"sidebar.docsSidebar.category.功能": {
|
||||
"sidebar.docsSidebar.category.功能特性": {
|
||||
"message": "Features",
|
||||
"description": "The label for category '功能' in sidebar 'docsSidebar'"
|
||||
"description": "The label for category '功能特性' in sidebar 'docsSidebar'"
|
||||
},
|
||||
"sidebar.docsSidebar.category.集成": {
|
||||
"message": "Integrations",
|
||||
|
||||
@@ -65,6 +65,55 @@ services:
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<div id="env">
|
||||
|
||||
### Option 3: Inject config from environment variables
|
||||
|
||||
</div>
|
||||
|
||||
Write <code>{'{{env.NAME}}'}</code> in the config, then pass values with `-e` or Compose `environment`. See [Environment Variables](./features/env.md) for the syntax.
|
||||
|
||||
```toml
|
||||
#orbien-server.toml
|
||||
listen = "{{env.ORBIEN_LISTEN:0.0.0.0:9527}}"
|
||||
|
||||
[auth]
|
||||
token = "{{env.ORBIEN_TOKEN}}"
|
||||
|
||||
[dashboard]
|
||||
addr = "0.0.0.0"
|
||||
port = 8020
|
||||
user = "{{env.DASHBOARD_USER:admin}}"
|
||||
password = "{{env.DASHBOARD_PASSWORD:123456}}"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yaml
|
||||
services:
|
||||
orbien-server:
|
||||
image: ghcr.io/orbien-org/orbien-server:latest
|
||||
container_name: orbien-server
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "9527:9527"
|
||||
- "8020:8020"
|
||||
environment:
|
||||
ORBIEN_TOKEN: ${ORBIEN_TOKEN}
|
||||
DASHBOARD_PASSWORD: ${DASHBOARD_PASSWORD}
|
||||
volumes:
|
||||
- ./orbien-server.toml:/etc/orbien/orbien-server.toml:ro
|
||||
```
|
||||
|
||||
```shell
|
||||
export ORBIEN_TOKEN=YOUR_TOKEN
|
||||
export DASHBOARD_PASSWORD=change-me
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
:::warning
|
||||
String fields must quote the placeholder. If a variable is unset and has no default, the process fails to start. Do not write <code>{'{{env.}}'}</code> in the desktop client's config.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Client
|
||||
|
||||
@@ -8,7 +8,11 @@ title: Authentication
|
||||
|
||||
Token authentication when the client connects to the server. If the server has no `token` (or it is empty), authentication is skipped.
|
||||
|
||||
The `token` on both sides must match, or login fails (`authorization failed`).
|
||||
When the server enables auth, both sides must use the same `token`, or login fails. The token is read from the config file. You can also inject it with environment variables; see [Environment Variables](./env.md).
|
||||
|
||||
:::tip
|
||||
At login the token is used to compute a digest. The token itself is never sent to the server in plaintext.
|
||||
:::
|
||||
|
||||
## Example
|
||||
|
||||
@@ -33,15 +37,3 @@ token = "YOUR_TOKEN"
|
||||
| Parameter | Required | Default | Description |
|
||||
|--------------|----------|---------|----------------------------------------------------------------------|
|
||||
| `auth.token` | No | | Shared secret; empty on the server disables auth; both sides must match |
|
||||
|
||||
## Command line
|
||||
|
||||
The server can also set this via a flag (it overrides `token` in the config file):
|
||||
|
||||
```shell
|
||||
./orbien-server -c orbien-server.toml -t YOUR_TOKEN
|
||||
```
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------------------|---------|---------------|
|
||||
| `-t` / `--token` | | Shared secret |
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
sidebar_label: Environment Variables
|
||||
title: Environment Variables
|
||||
---
|
||||
|
||||
# Environment Variables
|
||||
|
||||
Config files can reference process environment variables with `{{env.NAME}}`. This works anywhere you can inject env vars, including **Docker**, **systemd**, and **Kubernetes**.
|
||||
|
||||
:::warning
|
||||
The GUI client (`Orbien-Desktop`) does not support this syntax. Enter the actual value in the UI, not an expression.
|
||||
:::
|
||||
|
||||
## Syntax
|
||||
|
||||
```toml
|
||||
[auth]
|
||||
token = "{{env.ORBIEN_TOKEN}}"
|
||||
|
||||
[[tunnels]]
|
||||
name = "ssh"
|
||||
protocol = "tcp"
|
||||
service = "127.0.0.1:22"
|
||||
remotePort = {{ env.SSH_REMOTE_PORT:9000 } }
|
||||
```
|
||||
|
||||
| Form | Meaning |
|
||||
|-----------------------------------------|-------------------------------------------------------------------------|
|
||||
| <code>{'{{env.NAME}}'}</code> | Required. Startup fails if the variable is unset or empty |
|
||||
| <code>{'{{env.NAME:default}}'}</code> | Optional. Uses the default if the variable is unset or empty |
|
||||
| <code>{'"{{env.NAME}}"'}</code> | String fields: the placeholder must be inside quotes |
|
||||
| <code>{'{{env.NAME}}'}</code> | Numeric and boolean fields: do not quote |
|
||||
|
||||
Variable names may contain only letters, digits, and underscores, and must not start with a digit. Whitespace inside the braces is optional: <code>{'{{ env.NAME }}'}</code> is valid.
|
||||
|
||||
Only the first `:` is the default-value separator, so address-style defaults can be written as-is:
|
||||
|
||||
```toml
|
||||
listen = "{{env.ORBIEN_LISTEN:0.0.0.0:9527}}"
|
||||
server = "{{env.ORBIEN_SERVER:127.0.0.1:9527}}"
|
||||
```
|
||||
|
||||
For secrets, prefer the required form <code>{'{{env.ORBIEN_TOKEN}}'}</code>. Do not give the token a guessable default.
|
||||
Reference in New Issue
Block a user