常见问题

本文档记录了 SwanLab K8s 私有化版本部署过程中的常见问题。

【权限要求】部署服务是否需要较高部署权限（如部署 CRD 或 Controller）？

• 不需要。

【数据迁移】迁移数据时能否保证原服务不停机？

• ❌ 不能

迁移过程中必须停机原服务。如果不停止原服务会出现数据 gap。
此时可考虑使用swanlab sync将数据上传至新服务。

【节点指定】如何将 SwanLab 私有化服务 Pod 调度到指定节点？

在 values.yaml 中，所有服务均支持通过 customNodeSelector 字段指定节点选择器，Kubernetes 只会将 Pod 调度到满足对应标签的节点上。

给节点打标签：

kubectl label nodes <node-name> swanlab=true

示例：将 SwanLab Server 调度到带有 swanlab=true 标签的节点：

service:
  server:
    customNodeSelector: { "swanlab": "true" }

网关同样支持：

gateway:
  customNodeSelector: { "swanlab": "true" }

如需在存在污点（Taint）的节点上运行，可配合 customTolerations 一起使用：

service:
  server:
    customNodeSelector: { "swanlab": "true" }
    customTolerations:
      - key: "dedicated"
        operator: "Equal"
        value: "swanlab"
        effect: "NoSchedule"

TIP

customNodeSelector 与 customTolerations 为所有服务的通用字段，包括应用服务（gateway、vector、service.server、service.auth、service.house、service.cloud、service.next）和基础服务（dependencies.postgres、dependencies.redis、dependencies.clickhouse、dependencies.s3），按需为各服务单独配置即可。

【慢响应】如何测试集群与外部数据库之间的 RTT？

外接 PostgreSQL、Redis 或 ClickHouse 时，可以在集群中创建临时测试 Pod，测量集群节点与数据库实例之间的 RTT（Round-Trip Time，往返时延）。

PostgreSQL：

# 替换为实际的 PostgreSQL 连接串
kubectl run pg-client --rm -i --tty=false \
  --image=repo.swanlab.cn/public/postgres:16.1 \
  --restart=Never \
  -n <your_namespace> \
  -- sh -c '
export DATABASE_URL="postgres://xxxx:xx@<url>:<port_number>/app"
psql "$DATABASE_URL" -X -qAt <<'"'"'SQL'"'"'
\timing on
select 1;
select 1;
select 1;
select 1;
select 1;
select 1;
select 1;
select 1;
SQL
'

Redis：

# 替换为实际的 Redis 连接串
kubectl run redis-rtt --rm -i \
  --image=repo.swanlab.cn/self-hosted/redis-stack:7.4.0-v8 \
  --image-pull-policy=IfNotPresent \
  --restart=Never -n <your_namespace> -- \
  sh -c 'redis-cli -u "redis://<user>:<password>@<redis_host>:6379/0" --latency | awk "{printf \"min: %s ms | max: %s ms | avg: %s ms | samples: %s\n\", \$1, \$2, \$3, \$4}"'

ClickHouse：

# 替换为实际的 ClickHouse 用户名和密码
kubectl run ch-rtt --rm -i \
  --image=repo.swanlab.cn/self-hosted/clickhouse-server:24.3 \
  --image-pull-policy=IfNotPresent \
  --restart=Never -n <your_namespace> -- sh -c '
clickhouse-benchmark --concurrency 1 --iterations 1000 \
  --host <clickhouse_host> --port 9000 \
  --user <your_username> --password <your_passwd> \
  --query "SELECT 1" 2>&1 \
| awk "
/QPS:/ { split(\$0, x, \"QPS: \"); split(x[2], y, \",\"); qps=y[1]+0; avg=1000/qps }
/^99\\.000%/ { split(\$0, t, \" \"); p99=t[2]*1000 }
END { printf \"clickhouse RTT: avg=%.3f ms  p99=%.3f ms  (QPS %.2f)\n\", avg, p99, qps }
"
'

TIP

建议集群节点与数据库实例之间的 RTT 在 0.3ms 以内，尽量保证 SwanLab 服务所在节点与数据库处于同可用区，详见 自定义 value 配置。

【资源限制】如何限制 SwanLab 服务的 CPU 和 内存用量？

在 values.yaml 中，所有应用服务均支持通过 resources 字段设置 CPU 和内存的 Requests / Limits，格式与 Kubernetes 原生 resources 一致。

示例：限制 SwanLab Server 的资源用量：

service:
  server:
    resources:
      requests:
        cpu: "2"
        memory: "2Gi"
      limits:
        cpu: "4"
        memory: "4Gi"

各服务均可按需配置，未设置时默认不限制。基础服务（dependencies.postgres、dependencies.redis、dependencies.clickhouse、dependencies.s3）同样支持 resources 字段。

【镜像类】集群无法连接外网，如何下载、更新镜像？

• 您可提前在公网环境中，手动从 SwanLab 公共镜像仓库（即 repo.swanlab.cn）拉取全部所需镜像 (docker pull)，并上传至内网私有镜像仓库(docker push)。

【高可用】如何保障服务高可用与数据安全性？

根据数据库配置，主要针对两种情况进行分别设置：

针对使用本地数据库的情况：

• 部署过程中，每一个 PVC 申请对应一块独立云SSD硬盘，支持无感扩容。
• 由云硬盘本身做持久化存储，配置以天为单位的 快照策略，TTL 过期时间建议设置 2~7 天，保证每日数据可靠性。

针对外接云数据库的情况：

• 可由 IaaS 公有云本身的数据库主从同步进行保障，可联系各公有云厂商的云数据库产品技术支持、或自建集群的 DBA 进行相关对接配置。

【对象存储】实验图片上传失败/CSV和日志无法下载/头像显示异常？

此类问题与 S3对象存储 配置问题强相关，可以在 swanlab-house 对应的 pod 中定位到对应的服务报错日志，推荐排查顺序:

value.yaml 配置校验

• 首先校验一下 integrations.s3 中的配置是否正确，详见 外部 S3 集成配置

存储桶跨域规则配置

• 以阿里云 OSS 对象存储为例，配置示例为：

• 来源：建议放开到您公司内网域名的最顶级域名，如：您的内网域名为 ：domain.com，那么可以将来源设置为 *.domain.com
• 允许 Methods: GET, POST, PUT, HEAD
• 允许 Headers：填写 * 通配符
• 返回 Vary:Origin

public 桶ACL配置

• SwanLab 的默认用户头像使用「彩色 SVG」，如果无法正确显示，一般是 public 桶的公共读被关闭，以 阿里云 OSS 为例，可以在如下设置中开启

• 「权限控制」 -> 「阻止公共访问」，将按钮关闭

• 「权限控制」 -> 「读写权限」，开启公有读的 Bucket ACL