EOELAB

EOELAB 用户手册

EOELAB 用户手册

本文档说明如何注册账户、接入联邦网络并使用计算和对象存储等联邦设施。维护者同样先以用户身份完成账户和网络接入,再参考《EOELAB 运维手册》接入和维护自己负责的本地域与服务。具体地址参见《EOELAB 服务端点》,授权规则参见《EOELAB 权限模型》。

阅读导览

账户

账户注册

  1. 打开 Zitadel,自主注册或使用 GitHub 创建账户
  2. 完成账户注册后即成为 EOELAB 成员,无需管理团队审核
  3. 通过外部身份提供商创建的账户可能没有本地密码;需要本地密码时联系管理团队设置

成员可以立即将个人设备加入联邦网络。成员身份提供网络接入资格,不自动授予域标签、Incus 资源、RustFS 数据或 hs-console 管理员权限。架构规范要求通过 Headscale ACL 控制网络可达范围,而非默认全网互通;现网迁移进度及具体已开放路径由网络维护者确认,应用权限仍由对应服务管理。

每位使用者分别使用自己的账户,由资源维护者按职责分配权限,不共用登录账户。需要计算资源、多人共享数据空间或独立身份组织时,联系对应维护者或管理团队确认;独立身份组织不会自动分配业务资源。

需要分配资源时,说明使用场景、所需容量和使用负责人,并与维护者确认资源范围、业务维护、数据备份和恢复安排。首次使用可通过访问实例、上传下载对象或运行构建任务,验证所需权限与配置。

账户安全

联邦网络

接入网络

  1. 下载 Tailscale 客户端:https://tailscale.com/download
  2. 执行以下命令接入 EOELAB Headscale:
    sudo tailscale up --login-server https://hs.eoelab.org
    
  3. 按浏览器提示使用 EOELAB 账户登录
  4. 执行 tailscale status 确认设备在线

个人设备加入后使用自动生成的 HOSTNAME.eoelab 名称通信。独立服务可以通过 sidecar 拥有自己的 服务名.eoelab 网络端点,不必使用宿主机地址;服务接入与标签归属由维护者按《EOELAB 运维手册》配置。重装系统或清除 Tailscale 状态后需要重新注册。

在云服务器上激活客户端后,内部镜像域名可能解析到 CGNAT 地址。如软件源不可用,可临时改用公网站点,例如 USTC 镜像源。

管理自己的节点

  1. 打开 hs-console,使用 EOELAB 账户登录;公网控制台无需先接入 Tailscale,也不需要用户提供 Headscale 管理 API Token
  2. 在“节点”中查看设备;自己的无标签个人节点可以重命名、立即过期或删除,带标签节点按管理员范围授权
  3. 在“PreAuth Keys”中创建、使其过期或删除自己的无标签注册密钥;新 Key 原文只在创建响应中显示,应及时保存,列表不返回原文。使 Key 过期或删除 Key 不会自动删除已注册节点

普通新用户默认角色为 user。个人资源按 Headscale 用户 ID 判断归属;若提示尚未绑定,先使用相同 EOELAB 账户接入 Headscale 后重新登录,仍未匹配时联系管理团队核对绑定。

个人设备管理权限不包含自行绑定 core、volta 或 services 标签的权限。需要使用 tag:services 的机器或独立服务端点,由管理团队添加标签;用户向管理团队提供端点名称、用途和维护负责人,不自行添加该标签,注册节点也不会自动获得该标签。网络管理角色、标签授权、能力和限制统一参见《EOELAB 权限模型》。

中继与服务访问

Tailscale 优先让设备直接连接,无法直连时自动使用 DERP 中继。中国大陆的中继节点统一在 chn 区域内由客户端选择,无需手动选择城市。

需要远程访问服务时,将个人设备接入 Tailscale,再通过服务的联邦网络地址或 HOSTNAME.eoelab 访问;连接须符合网络 ACL,连接成功后仍按应用自身要求完成认证。设备在线不代表可以访问全部服务,无法连接时应同时核对目标地址、网络策略和服务状态。EOELAB 不再为各应用单独建设专用中继。节点覆盖、规格和禁止转售等使用约定参见《EOELAB 互联云架构规范》的“DERP 中继”。

计算服务

Incus 使用 Zitadel OIDC 登录,并通过 OpenFGA 控制用户可以访问的项目、实例和其他资源。core0 Incus Web UI 同时提供公网和联邦网络私网入口;节点 SSH、实例 proxy 端口和其他节点直连入口只在联邦网络内提供。角色和细粒度权限说明参见《EOELAB 权限模型》。

首次使用时,先与本地域维护者确认分配的项目、实例、资源规格和权限。登录成功但看不到业务资源时,应核对资源授权,不必重复注册账户。

实例访问

  1. 打开所在本地域的 Incus Web UI,使用 terminal 或 console 操作实例;core0 的公网入口为 https://core0.eoelab.org,接入 Tailscale 后也可使用私网入口 https://core0-1.eoelab。两个入口使用相同的账户和资源权限
  2. 需要使用 SSH 或 SCP 时:
    1. 将设备接入联邦网络
    2. 由维护者通过 proxy 设备配置 SSH 端口,并绑定到 Incus 节点的 Tailscale 接口
    3. 使用实例所在节点的 .eoelab 名称和分配端口连接;core0 的节点名称为 core0-1.eoelab
    4. 通过 terminal 将公钥写入实例
    5. 启动 SSH 服务:
      • Debian 系:service ssh start
      • Alpine 系:/usr/sbin/sshd
    6. 使用 SSH 或 SCP 连接

嵌套 OCI 容器

默认不允许在 LXC 中嵌套运行 OCI 容器。容器化服务应直接以 OCI 实例运行在 Incus 上,并使用 Incus 网络通信。CI/CD 构建镜像时可以使用 Kaniko。

授权控制台

  1. 打开 fga-console,通过 EOELAB Zitadel 账户登录;公网入口无需先接入 Tailscale,也不需要向浏览器提供 OpenFGA API Token
  2. 选择所负责的本地域实例,如 core 或 volta,再进入相应 Store
  3. 在模型列表选择具体版本,查看关系定义、JSON 或按需生成的 DSL;Check、Expand、List Objects 和 List Users 均在所选模型版本下执行
  4. 在 Tuples 页面按 user、relation、object 精确筛选并翻页;获得相应写权限的维护者可以新增或删除关系,Changes 用于按对象类型查看变更

普通新用户默认只读。需要写入时,联系管理团队分配相应实例权限;控制台角色与 Incus 资源权限的区别参见《EOELAB 权限模型》。

页面分别显示实例健康、实例认证和控制台写权限。登录成功、角色可写不代表实例 Token 已通过认证;若实例检查失败,向维护者提供页面中的 HTTP 状态或错误原因,不必反复重新登录。页面不进行后台轮询,已加载 JSON 的查看和 DSL 转换不会发起新的授权查询。

对象存储

EOELAB 对象存储由 RustFS 提供,兼容 S3,并提供 Console 和 WebDAV 接口。Console 公网管理入口为 https://oss-console.eoelab.org。S3 和 WebDAV 同时提供公网与私网入口,两类入口使用相同的凭证和权限规则:

接口公网 HTTPS 入口联邦网络私网入口
S3https://oss.eoelab.org/http://oss.eoelab:80
WebDAVhttps://dav.eoelab.org/http://oss.eoelab:8080

公网入口无需接入 Tailscale;私网入口使用前必须先接入 EOELAB Tailscale 网络。以下示例使用公网 HTTPS 入口。

对象存储分为热层和冷层,用户始终使用 oss。oss-cold 仅作为服务端的冷数据分层目标,不向用户开放,无需配置或直接访问;冷数据读取仍通过 oss 的 Bucket 和对象键完成。

只有 S3 Tables 表存储桶常驻热层;其余热层 Bucket 均采用当前版本 7 天转冷规则,用户、公共和设施用途的非表 Bucket 使用相同策略。7 天从对象最后修改时间计算,默认按 UTC 日界向上取整,再由后台异步转换,不保证满 168 小时立即完成;读取不会重新计时。历史版本需单独配置非当前版本转换规则。转冷不删除对象,也不改变访问路径和权限,但读取依赖冷层服务及其网络路径。

RustFS 目前不会为新建 Bucket 自动添加默认生命周期配置,因此管理团队需要手动为非表存储桶补齐统一的转冷规则,无需用户自行添加。配置完成后,对象由 RustFS 按规则自动转冷。

登录 Console

  1. 打开 RustFS Console
  2. 选择 OIDC 登录
  3. 使用 EOELAB Zitadel 账户完成认证

Console 中创建的 Access Key 是独立的长期凭证,用于 rc、S3 SDK 和 WebDAV。Secret Key 通常只在创建时显示一次,应立即存入密码管理器。

Bucket 命名

每个用户只能创建和管理以下名称的个人 Bucket:

<sub>
<sub>-*

sub 是 Zitadel 为账户分配的稳定用户 ID,可以在 Zitadel 用户资料中查看,或向管理团队查询。例如 sub 为 123456 时,可以创建 123456、123456-backup 和 123456-project-a,不能创建 backup。

所有有效成员还可以只读访问设施预先创建的 dataset 和 iso 公共 Bucket,但不能在其中上传、修改或删除对象。首次访问对象存储时,即使尚未创建个人 Bucket,rc ls oss/ 也会列出这些公共 Bucket。

dataset 和 iso 中内容的权利仍归原作者、发布者或相应权利人所有。访问和使用这些资源前必须阅读《EOELAB 公共数据资源规则》,并继续遵守原始许可证、使用条款和引用要求;联邦成员只读权限不代表资源属于公有领域或可以任意使用。

Bucket 名称必须符合 S3 命名规则:使用小写字母、数字、点和连字符,不能包含空格或下划线。

以上是默认个人资源规则。多人共享 Bucket 的归属和访问策略须由对象存储维护者另行配置,不能通过共享个人账户或个人 Access Key 代替各使用者所需的授权。

创建 Access Key

  1. 在 Console 打开 Access Keys
  2. 选择创建 Access Key
  3. 根据用途填写名称、说明和有效期;除非确有长期使用需求,否则必须设置有效期
  4. 保存 Access Key 和 Secret Key

Access Key 继承当前用户的权限边界。即使为 Access Key 配置额外策略,也不能突破用户自己的 Bucket 范围。

安装 rc

从 https://github.com/rustfs/cli/releases 下载与操作系统和处理器架构匹配的发布包。以 Linux amd64 为例:

tar -xzf rustfs-cli-linux-amd64-vVERSION.tar.gz
sudo install -m 0755 rc /usr/local/bin/rc
rc --version

将 VERSION 替换为下载的版本号。安装后的命令名为 rc。

配置 rc

使用 Console 创建的 Access Key 和 Secret Key 配置别名:

rc alias set oss https://oss.eoelab.org/ ACCESS_KEY SECRET_KEY

如需使用私网入口,先接入 Tailscale,再将命令中的地址替换为 http://oss.eoelab:80。不要将包含真实 Secret Key 的命令提交到 Shell 脚本、Git 仓库、工单或聊天记录中。

常用操作:

# 列出可访问的 Bucket
rc ls oss/

# 创建 Bucket
rc mb oss/SUB
rc mb oss/SUB-project

# 上传文件或目录
rc cp ./example.txt oss/SUB-project/
rc cp -r ./dataset/ oss/SUB-project/dataset/

# 下载文件
rc cp oss/SUB-project/example.txt ./example.txt

# 删除空 Bucket
rc rb oss/SUB-project

将示例中的 SUB 替换为自己的 Zitadel sub。

Access Key 生命周期

Access Key 到期后立即停止认证。RustFS 在后续加载该身份时自动删除过期的 Service Account 记录和关联策略,因此正常轮换可以通过设置有效期完成,不需要在到期后手动清理服务端记录。

需要提前撤销时,先查看自己名下的 Access Key:

rc admin service-account ls oss

删除指定 Access Key:

rc admin service-account rm oss ACCESS_KEY

如果删除的是当前 oss Alias 使用的 Access Key,服务端删除成功后再清理本地 Alias:

rc alias remove oss

rc alias remove 只删除本地配置,不会撤销 RustFS 服务端凭证。必须先执行 rc admin service-account rm,再删除本地 Alias。

使用其他 S3 客户端

支持自定义 S3 Endpoint 的客户端使用以下配置:

Endpoint: https://oss.eoelab.org/
Access Key: Console 创建的 Access Key
Secret Key: Console 创建的 Secret Key
Region: us-east-1
Path Style: 按客户端兼容性需要启用
TLS: 开启

使用私网入口时,先接入 Tailscale,将 Endpoint 改为 http://oss.eoelab:80 并关闭 TLS,应用流量由 Tailscale 加密。两类入口均使用 Access Key 和 Secret Key 完成应用身份认证。

使用 WebDAV

连接 WebDAV 公网地址 https://dav.eoelab.org/,或在接入 Tailscale 后使用私网地址 http://oss.eoelab:8080。用户名填写 Access Key,密码填写 Secret Key。WebDAV 不支持 OIDC/STS 临时凭证,因为 Basic Auth 无法携带 Session Token。

浏览器工作台

打开 dav-console,使用 RustFS Access Key / Secret Key 登录,即可浏览和操作文件。首次使用先按上文“创建 Access Key”获取凭证;文件权限沿用 RustFS 的现有授权。

使用系统或其他 WebDAV 客户端

建议在连接地址中显式填写 Access Key,避免客户端继续使用缓存的旧用户名:

https://<ACCESS_KEY>@dav.eoelab.org/[<BUCKET>/]

[<BUCKET>/] 表示可选路径。省略时从 WebDAV 根目录开始并列出当前 Access Key 可访问的 Bucket;填写时直接进入指定 Bucket。由于 Access Key 已经作为用户名写入地址,客户端可能只显示密码输入框,此时填写对应的 Secret Key 即可。

WebDAV 根路径列出当前 Access Key 可访问的 Bucket,Bucket 和对象路径对应如下:

https://<ACCESS_KEY>@dav.eoelab.org/                      Bucket 列表
https://<ACCESS_KEY>@dav.eoelab.org/<BUCKET>/             指定 Bucket
https://<ACCESS_KEY>@dav.eoelab.org/<BUCKET>/<OBJECT>     指定对象

不要直接用网页浏览器验证 WebDAV。浏览器访问根地址时发送普通 GET /,服务端返回 405 Method Not Allowed 属于正常现象。可以使用以下命令验证;命令会交互式询问 Secret Key,避免将其写入 Shell 历史:

ACCESS_KEY='<ACCESS_KEY>'
curl --user "$ACCESS_KEY" -X PROPFIND -H 'Depth: 1' https://dav.eoelab.org/

成功时返回 207 Multi-Status。常见客户端配置如下:

客户端地址认证
GNOME Filesdavs://<ACCESS_KEY>@dav.eoelab.org/,可追加 Bucket 路径地址中提供 Access Key,密码为 Secret Key
macOS Finderhttps://<ACCESS_KEY>@dav.eoelab.org/,可追加 Bucket 路径地址中提供 Access Key,密码为 Secret Key
Windows、Cyberduck、rclone 等https://dav.eoelab.org/,可追加 Bucket 路径显式将 Access Key 设为用户名,Secret Key 设为密码

使用私网入口时,将示例中的 https://dav.eoelab.org/ 替换为 http://oss.eoelab:8080/;GNOME Files 使用 dav://<ACCESS_KEY>@oss.eoelab:8080/。

只读 Access Key 可以列目录和下载对象,不能上传、创建目录、重命名或删除。公网入口使用 HTTPS,私网入口的 HTTP 明文流量由 Tailscale 加密;两类入口均须使用 Access Key 和 Secret Key 完成应用身份认证。

S3 Tables

获得相应权限的用户可以在 Console 的 S3 Tables 页面启用自己的 Bucket,并管理 Namespace、Table 和 View。Table 操作仍受 <sub> 和 <sub>-* 的 Bucket 边界限制。

表存储桶常驻热层,转冷规则的排除与调整由管理团队统一处理;如已有对象转入冷层,联系管理团队确认处理方式,移除转换规则不会自动回迁已有对象。

常见问题

502 Bad Gateway

如果客户端配置了 HTTP 代理,.eoelab 请求可能被错误发送到代理。将内部域名加入代理绕过列表:

export NO_PROXY="${NO_PROXY:+${NO_PROXY},}.eoelab"
export no_proxy="${no_proxy:+${no_proxy},}.eoelab"

可以使用以下命令进行单次验证:

NO_PROXY='*' no_proxy='*' rc ls oss/

AccessDenied

依次检查:

  1. 写操作的 Bucket 名称是否为自己的 <sub> 或 <sub>-*;dataset 和 iso 对普通成员只读
  2. Access Key 是否属于当前用户且未被禁用或过期
  3. Access Key 的附加策略是否进一步缩小了权限
  4. 设备是否已接入联邦网络

SignatureDoesNotMatch

检查 Endpoint、Access Key、Secret Key 和系统时间。复制凭证时不要包含额外空格或换行。

Console 中没有创建 Bucket 按钮

当前 Console 可能无法识别包含动态用户变量的 Bucket Resource。可以改用 rc mb 创建符合命名规则的 Bucket;后端仍会执行完整的权限检查。

镜像仓库

EOELAB 使用阿里云 OCI 仓库 crpi-0fzeutaz68uv7lwt.cn-hangzhou.personal.cr.aliyuncs.com 提供自建镜像和已同步的上游镜像:

镜像引用格式:

crpi-0fzeutaz68uv7lwt.cn-hangzhou.personal.cr.aliyuncs.com/eoelab/<REPO>:<TAG>
crpi-0fzeutaz68uv7lwt.cn-hangzhou.personal.cr.aliyuncs.com/upstream/<REPO>:<TAG>

将 <REPO> 和 <TAG> 替换为对应构建或同步任务输出的仓库名和标签。需要增加上游镜像时,联系维护者添加同步任务;仓库密钥不公开分发。

Docker Hub 公网镜像代理已移除。已有配置应移除旧代理地址,改用所需镜像对应的阿里云仓库引用。

自托管 Runner

申请 Runner

  1. 在 Codeberg Actions 页面创建新的 Runner
  2. 将以下信息发送给管理团队:
    connections:
      forgejo:
        url: https://codeberg.org/
        uuid: UUID
        token: TOKEN
    

实际注册时,维护者会将 forgejo 替换为申请人的用户名,用于内部区分并避免同名 key 冲突。

工作流选择 Runner

通用 Runner 按资源规格和处理器架构选择。当前可用配置为:

runs-on: [medium, amd64]

工作流中不再填写 vm、lxc 或 host 标签。专用 Runner 按用途选择,mirror 仅用于镜像或软件包同步,不承接通用构建任务。资源规格与可用 Runner 参见《EOELAB 互联云架构规范》的“自托管 Runner”。

现有 Runner 运行在具备内核特权的 VM 或宿主机环境中;使用作业容器时,所需设备、挂载和特权能力仍取决于执行配置。

退出与数据清理

停止参与项目或交接业务

停止参与某个项目或不再承担原有职责,不等于退出 EOELAB。先与项目负责人和资源维护者交接业务配置、节点、自动化凭证和数据,并回收对应权限;仍参与其他项目时保留相应账户与权限。

自动化凭证应记录用途和负责人。若凭证依附于不再参与项目的人员账户,应在撤销原权限或删除账户前完成替换和验证;RustFS Service Account 的有效权限受父 OIDC 用户权限约束。

退出联邦

需要退出联邦时,联系管理团队协调账户、节点和权限清理,并提前说明需要导出的配置和数据。管理团队与用户确认必要的数据交付和清理范围后移除相应接入。删除账户前,应完成依附于该账户的共享资源与服务凭证交接。

长期失联或存在安全风险的账户和节点可能被强制移除。