EOELAB

EOELAB 运维手册

EOELAB 运维手册

本文档面向负责本地域、实例和业务服务的维护者,说明如何接入 EOELAB 已有设施、配置所负责的资源并完成日常维护。联邦控制设施与公共对象存储由管理团队统一维护,维护者按本文说明接入和使用。账户、对象存储和 Access Key 等使用方法参见《EOELAB 用户手册》,技术约束参见《EOELAB 互联云架构规范》,权限等级和授权设计参见《EOELAB 权限模型》。

阅读导览

本地域与节点初始化

接入本地域或独立服务端点前,与管理团队确认设施名称、用途、资源规模、所有者和维护负责人,以及业务维护、数据备份和恢复责任。联系方式参见《EOELAB 互联云架构规范》的“公共联系方式”。独立服务按本文“服务接入”章节配置;未纳入具体本地域网络管理时,由管理团队为机器或服务端点添加 tag:services,纳入 services 服务归属组,无需为此建设 Incus 计算设施。

本地域是联邦实体,域内节点包括计算、存储和服务宿主等资源。节点不单独构成联邦实体,其归属由所在本地域确定。

基础配置

  1. 安装 Debian stable;需要 Incus 计算设施时再安装 Incus stable(https://github.com/zabbly/incus)
  2. 根文件系统使用 Btrfs,并配置 raid1/10
  3. 域内节点主机名使用 DomainPrefix-Number,例如 core1-1;Incus 节点同样使用该格式
  4. 维护者先按《EOELAB 用户手册》获得账户并接入联邦网络,再建立所需的 Incus 或 Ceph 集群
  5. 禁用 swap:
    • 安装系统时不创建 swap 分区
    • 执行 swapoff -a 并永久移除 /etc/fstab 中的 swap 条目
  6. 仅使用 SSH 密钥登录,关闭密码验证
  7. 通过 systemd-timesyncd 同步 UTC,无需额外配置 NTP

计算设施操作

配置 Incus 镜像源

Incus 镜像首选入口为 https://mirrors.sdu.edu.cn/lxc-images-auto/,协议为 simplestreams,公共镜像无需认证。

替换已有的 images remote:

incus remote remove images
incus remote add images https://mirrors.sdu.edu.cn/lxc-images-auto/ --protocol=simplestreams --public
incus remote list
incus image list images:

首选入口不可用时,切换到 Linux Containers 官方源:

incus remote set-url images https://images.linuxcontainers.org/

OIDC + OpenFGA 接入

Incus 不再使用 TLS 客户端证书作为用户登录或本地域维护者的鉴权方式。所有用户通过联邦认证设施 Zitadel 使用 OIDC 登录。core0 Incus Web UI 同时提供公网与联邦网络私网入口,节点 SSH、实例 proxy 端口和其他节点直连入口只允许通过联邦网络访问。

OIDC 负责确认用户身份,OpenFGA 负责确认用户对 Incus 资源的访问权限。完成 OIDC 登录后,必须在 OpenFGA 中为用户或用户所属组配置关系元组,未配置授权关系的用户不会获得业务资源权限。

对象格式、角色继承、entitlement、最小权限和安全边界统一参见《EOELAB 权限模型》。关系元组的增删和查询在 fga-console 中完成。

嵌套 OCI 容器

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

数据设施操作

存储接口、数据保护策略和驱动选型遵循《EOELAB 互联云架构规范》RFC-0004。

接入 TrueNAS 共享存储

  1. 节点命名为 DomainPrefix-nas,例如 core0-nas
  2. 计算节点通过其 .eoelab 名称访问存储

接入 Ceph 共享存储

  1. 独立节点命名为 DomainPrefix-ceph-Number,超融合节点沿用 Incus 节点名称
  2. 节点和客户端使用 .eoelab 名称

使用公共对象存储

业务服务通过 oss 的 S3 入口访问对象存储,按《EOELAB 用户手册》配置独立的业务凭证,并验证服务端点到 oss 的网络连通性与数据权限。多人共享 Bucket 或额外数据权限由管理团队协调配置。

冷热分层及生命周期规则由管理团队统一维护。只有 S3 Tables 表存储桶常驻热层,其他热层 Bucket 均采用统一的 7 天转冷规则。由于 RustFS 不会为新建 Bucket 自动添加默认生命周期配置,管理团队需要手动补齐规则;配置后由 RustFS 自动执行对象转换,业务维护者无需自行配置 Tier 或添加规则。具体使用行为参见《EOELAB 用户手册》。

接入统一认证与授权

Zitadel 和 OpenFGA 由 EOELAB 提供。为本地域的 Incus 计算设施接入统一认证与授权时,将 Incus Web UI 的所有公网、私网入口及各自的 OIDC 回调地址交给管理团队,并取得 Application ID、对应 OpenFGA 实例地址、API Token 和 Store ID,随后配置自己的 Incus。

core0 在同一个 Zitadel OIDC 应用的 Redirect URIs 中登记以下两个回调地址:

https://core0.eoelab.org/oidc/callback
https://core0-1.eoelab/oidc/callback

其他部署 Incus 的本地域使用自身各 Web UI 入口地址加 /oidc/callback,协议、主机名、端口和路径必须与实际登录请求中的 redirect_uri 匹配。同一套 Incus 的公私网入口共用一个应用即可;不同本地域默认分别登记应用,以便独立配置和维护。登记多个回调地址不授予跨本地域的资源权限,资源授权仍由对应 OpenFGA 配置决定。

分别从公网和私网入口验证 OIDC 登录,确认授权请求携带对应入口的回调地址,且浏览器能访问该地址。经过反向代理时检查外部主机名和协议的传递;如使用登出后跳转,也应在 Post Logout Redirect URIs 中登记实际使用的地址。

Incus 配置 OIDC

Incus 配置 OpenFGA

通过 fga-console 管理授权

  1. 打开 fga-console,使用 EOELAB 账户登录,选择所负责的实例和 Store;Incus 使用的 Store ID 可从 openfga.store.id 核对
  2. 按《EOELAB 权限模型》新增或删除 user / relation / object 关系元组;需要写权限时,联系管理团队分配对应实例的 admin 权限
  3. 在实际使用的模型版本下执行 Check 或 List Objects,再通过 Incus 验证资源访问结果

日常授权通过关系元组调整。Incus 使用的模型以设施实际注册的版本为准,不因新增用户或分配项目权限而另建模型。实例健康或认证异常时,将页面错误详情提供给管理团队处理。

网络设施操作

连接检查

使用 tailscale status 查看连接状态,使用 tailscale ping HOSTNAME.eoelab 验证实际路径。集群和存储节点经 DERP 中继时按降级状态处理。

服务接入

  1. Tailscale 是基础网络设施;先确认服务的网络管理归属、端点名称和 ACL,再配置 .eoelab 寻址并按批准的访问范围提供用户入口
  2. 用户入口分为公网和联邦网络两类,不要求同一服务同时提供两类入口
  3. 主站与公网控制面使用 eoelab.org;需要向公网开放自托管后端控制服务时,向管理团队申请子域名和 Cloudflare Tunnel 路由;Workers 等托管控制面使用平台自定义域名提供入口
  4. Cloudflare Tunnel 源站使用 http://localhost:PORT 或 http://HOSTNAME.eoelab:PORT,不配置源站 TLS
  5. 只允许联邦网络访问的服务不得配置公网 DNS、Cloudflare Tunnel 路由或其他公网反向代理
  6. 联邦内部服务默认使用 .eoelab 名称和协议的非 TLS 模式,例如 PostgreSQL 可设置 sslmode=disable;core0 Incus Web UI 私网入口 https://core0-1.eoelab 使用 HTTPS,需维护客户端信任且覆盖该主机名的服务端证书
  7. 应用明文流量必须全程位于 Tailscale 或 Cloudflare Tunnel 内,其他路径必须启用协议加密
  8. 数据库账户、OIDC、Token、OpenFGA 和 RustFS Policy 等应用认证与授权保持启用
  9. core0 Incus Web UI 和 RustFS S3 同时提供公网与联邦网络私网入口;RustFS Console 提供公网管理入口;节点 SSH、实例 proxy 端口等直连入口只提供联邦网络入口
  10. 非 HTTP/HTTPS 服务不得向公网开放

服务网络身份与 sidecar

独立部署的服务优先使用 Tailscale sidecar 或等效的独立网络端点,需要主机级网络身份的域内节点继续采用主机级接入。服务端点的网络身份与宿主机分别管理。

  1. 确认谁负责服务端点的接入、标签授权、ACL 协调和退出清理,并记录业务维护负责人
  2. 纳入具体本地域网络管理的端点使用对应标签,例如 tag:core、tag:volta;未纳入具体本地域网络管理的独立服务端点及其宿主节点,由管理团队添加 tag:services,不自动分配,也不由用户自行添加
  3. 本地域标签的注册方式向管理团队或获授权的域维护者取得;使用 tag:services 时,向管理团队提供机器或端点名称、所有者和维护负责人,由管理团队通过管理接口完成标签分配并协调 ACL,不向用户提供自行授予该标签的权限或注册凭证;核心本地域的公共属性不代表任何成员都可绑定 core
  4. 使用联邦内唯一的服务端点名称,客户端通过 服务名.eoelab 访问;名称不依赖宿主机名称,域标签也不根据宿主机位置自动继承
  5. 为服务持久化并保护独立的 Tailscale 状态和凭证,不与宿主机、其他服务或同时运行的副本复用身份状态
  6. 明确服务与 sidecar 的共享网络范围、监听接口和转发目标,按协议选择 TUN 或 userspace networking,并验证实际入站和出站连接
  7. 避免保留绕过 ACL 的额外监听或转发入口,继续执行既定的公网或联邦网络访问范围以及应用认证授权
  8. 服务迁移时先协调旧端点停用和身份交接;归属变更时同步调整标签及 ACL,下线时清理端点、注册凭证和无用规则

services 是由管理团队管理的服务归属组,不是 Headscale 内置或自动加入的默认组,也不是本地域,不要求部署 Incus。本地域是联邦实体,域内节点只是域内资源;services 中的宿主节点仍须归属某个本地域,网络管理归属与资源归属可以不同。服务托管位置、网络管理归属和业务维护责任分别确认。

协调联邦网络访问

接入或调整服务时,向网络维护者提供所负责节点与服务端点的名称、网络归属、维护负责人,以及需要连通的来源、目标、协议和端口。分别说明用户访问、管理入口、服务依赖、监控及集群和存储通信路径,由获授权的网络维护者配置联邦网络策略。

配合验证必要连接与不应开放的路径,尤其确认集群心跳、存储复制和管理入口保持可用。网络归属、服务依赖变更或服务下线时,同步通知网络维护者调整相应规则。具体已开放路径与现网策略迁移进度由网络维护者确认。

Headscale ACL 管理联邦网络端点之间的连接,下面的 Incus ACL 管理实例虚拟网络,两者分别配置。

虚拟网络配置

  1. 单节点使用 bridge,集群使用 OVN,整个本地域有且仅有一个虚拟网络
  2. 用户态接口命名为 INTERFACE-Domain
  3. 地址池默认使用 172.16.0.0/12
  4. 实例默认接入设备 eth0;VM 需要 proxy 设备时可设置静态地址:
    eth0:
        ipv4.address: 实例静态 IP
        network: 接入网络
        type: nic
    
  5. 未采用独立服务网络端点接入的实例,使用 proxy 设备将端口转发到节点,服务接入方式按“服务接入”章节配置;采用 sidecar 等服务级接入时按服务端点配置入口,不要求经宿主机转发。proxy 配置如下:
    • 容器(LXC/OCI):listen 为外部端口,connect 为内部端口
    • VM:启用 NAT mode,listen 绑定节点的 Tailscale 接口,访问端使用 HOSTNAME.eoelab;connect 的 IP 为实例静态 IP

Incus 虚拟网络 ACL 配置示例

  1. block-host:丢弃主机地址段流量
    • Drop Any 10.0.0.0/8
    • Drop Any 192.168.0.0/16
  2. block-internal:丢弃内部地址段流量
    • Drop Any 172.16.0.0/12

日常维护与交接

管理资源权限

  1. 根据实际职责,为使用者或用户组分配所负责资源的权限,具体角色参见《EOELAB 权限模型》
  2. 通过 fga-console 管理有权操作的 Incus 关系元组,并验证实际资源访问
  3. 使用对象存储时,按《EOELAB 用户手册》配置 Access Key;需要共享 Bucket 或额外数据权限时联系对象存储维护者
  4. 权限或职责变更后,核对使用者访问范围,回收不再需要的授权
  5. 涉及账户停用、其他使用者的节点或联邦设施管理的问题,联系管理团队处理

管理所负责的节点

用户按《EOELAB 用户手册》接入网络。维护者需要确认:

在 hs-console 中,仅对有权管理的节点执行重命名、过期、删除、标签或批准路由操作。标签变更必须同时满足原节点归属和目标范围要求,多标签资源须全部处于管理员范围内;不能通过改标签接管其他资源。个人无标签 Key 仅能管理自己的,域内标签 Key 按已分配范围管理,新密钥原文只在创建响应中显示。

需要调整全局 ACL、group、tagOwners、Headscale 用户或控制台角色/范围时,联系 super_admin。ACL 校验不保存,保存直接提交原文;修改后应按预期来源和目标验证实际连通性。职责交接时同步回收控制台范围、标签 Key 和不再需要的网络授权。

退出与清理

维护职责变更或停止参与项目时,先核对对应的资源权限、节点所有权和自动化凭证,完成交接后回收不再需要的权限。成员仍参与其他项目时保留其他授权,不直接按退出联邦处理。

停止使用服务或移除本地域前,完成所负责业务的配置、数据和凭证交接,并与管理团队确认节点移除、权限回收及数据清理范围。需要退出联邦时,按《EOELAB 用户手册》联系管理团队办理。

接入检查清单

本地域与节点

数据设施

网络设施

联邦接入