将 S3 存储挂载到 Sandbox

每个 Sandbox 实例默认配备 20GB 的临时系统盘存储,用于临时数据操作。当 Sandbox 终止或超时后,该存储空间内的所有数据都会被自动清除。因此,需要长期保留的持久化数据应存储在外部云存储服务中。 Sandbox 的存储配置规格可能会调整。请查阅定价文档了解最新的资源配置和相关费用。在 Sandbox 中使用对象存储桶通常有两种方式:

直接使用云服务商的 SDK、CLI 或 REST API。
使用基于 FUSE 的文件系统挂载存储桶,让应用程序可以通过文件路径访问对象。

FUSE (Filesystem in Userspace) 是一个内核模块和用户态库,允许在用户态应用程序中实现功能完整的文件系统。该框架提供了一个抽象层,将远程云存储服务呈现为标准的文件系统层级结构,从而可以通过常规的 POSIX 接口透明地进行文件操作。本文档全面介绍如何通过文件系统挂载的方式,将主流云服务商的对象存储桶集成到 Sandbox 环境中。

基于 FUSE 的对象存储挂载会因网络延迟和协议转换层而带来显著的 I/O 性能开销,对性能有严格要求的应用应避免使用这种方式。此外,FUSE 文件系统操作不具备原生对象存储 API 固有的原子性保证,可能出现本地文件系统操作成功而对应的远端操作失败的竞态情况,从而导致数据不一致。这种挂载方式最适合以读为主、写操作较少且对性能要求宽松的工作负载。对于性能敏感或写入频繁的应用,强烈建议直接使用云服务商 SDK 或原生 REST API 进行集成。

Amazon S3

使用 s3fs-fuse(一个基于 FUSE 的文件系统实现,可通过标准文件操作访问 S3 存储桶),可以将 Amazon S3 存储桶挂载为 POSIX 兼容的文件系统。 s3fs-fuse 软件包既可以在创建 Sandbox Template 时,通过在 ppio.Dockerfile 中加入安装命令来集成; 也可以在运行中的 Sandbox 实例内按需动态安装。另外我们也提供了PPIO 官方的模板 s3fs-fuse。 模板 Dockerfile 构建：

# 兼容基于 Debian 的发行版
FROM ubuntu:latest

# 重要：s3fs 1.93 以下版本存在已知挂载问题，请确保版本兼容。
RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y s3fs

以下实现演示了如何使用 s3fs-fuse 模板在 Sandbox 环境中以编程方式挂载 AWS S3 存储桶:

import os
import time

from ppio_sandbox import PPIO

ppio = PPIO()

AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID')
AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY')
AWS_BUCKET_NAME = os.environ.get('AWS_BUCKET_NAME')
AWS_REGION = os.environ.get('AWS_REGION')
if not AWS_ACCESS_KEY_ID or not AWS_SECRET_ACCESS_KEY or not AWS_BUCKET_NAME or not AWS_REGION:
    raise ValueError('Required environment variables not configured: PPIO_API_KEY, PPIO_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')

MOUNT_DIRECTORY = '/mnt/s3-bucket'

sandbox = ppio.sandbox.create("s3fs-fuse", envs={})

# 初始化挂载点
sandbox.files.make_dir(MOUNT_DIRECTORY)

# 配置 s3 认证信息
sandbox.files.write('/root/.passwd-s3fs', f'{AWS_ACCESS_KEY_ID}:{AWS_SECRET_ACCESS_KEY}')

# 设置认证文件权限
sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

# 使用 s3fs 将目录挂载至挂载点
# 参考：https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
mount_options = f'allow_other,endpoint={AWS_REGION}'
sandbox.commands.run(f'sudo s3fs {AWS_BUCKET_NAME} {MOUNT_DIRECTORY} -o {mount_options}')

# 等待挂载就绪，你也可以构建一个template，让挂载指令随系统启动时生效
const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
time.sleep(3)

# 尝试写入文件
sandbox.files.write(f'{MOUNT_DIRECTORY}/test-file.txt', 'test-file-content')

# 验证文件是否写入成功，这时可以查看 bucket 的后台看下是否存在该文件
content = sandbox.files.read(f'{MOUNT_DIRECTORY}/test-file.txt')
print('File content:', content)

sandbox.kill()

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME
const AWS_REGION = process.env.AWS_REGION
if (!AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_BUCKET_NAME || !AWS_REGION) {
  throw new Error('Required environment variables not configured: PPIO_API_KEY, PPIO_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')
}

const MOUNT_DIRECTORY = '/mnt/s3-bucket'

const sandbox = await ppio.sandbox.create("s3fs-fuse")

// 初始化挂载点
await sandbox.files.makeDir(MOUNT_DIRECTORY)

// 配置 s3 认证信息
await sandbox.files.write('/root/.passwd-s3fs', `${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}`)

// 设置认证文件权限
await sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

// 使用 s3fs 将目录挂载至挂载点
// 参考：https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
const mountOptions = `allow_other,endpoint=${AWS_REGION}`
await sandbox.commands.run(`sudo s3fs ${AWS_BUCKET_NAME} ${MOUNT_DIRECTORY} -o ${mountOptions}`)

// 等待挂载就绪，你也可以构建一个template，让挂载指令随系统启动时生效
const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
await sleep(3000);

// 尝试写入文件
await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

// 验证文件是否写入成功，这时可以查看 bucket 的后台看下是否存在该文件
const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
console.log(content)

await sandbox.kill()

腾讯云 COS

使用 cosfs（腾讯云基于 s3fs-fuse 开发的 FUSE 文件系统实现），可以将腾讯云 COS 存储桶挂载为 POSIX 兼容的文件系统。我们同样提供了 PPIO 官方模板 cosfs-fuse，其中已预装 cosfs；你也可以在自定义 Template 的 ppio.Dockerfile 中自行安装，或在运行中的 Sandbox 实例内按需动态安装。 模板 Dockerfile 构建：

# 兼容基于 Debian 的发行版
FROM ubuntu:24.04

RUN sudo apt update && sudo apt install libfuse-dev libcurl4-openssl-dev libxml2-dev libssl-dev wget -y

RUN wget https://github.com/tencentyun/cosfs/releases/download/v1.0.25/cosfs_1.0.25-ubuntu24.04_amd64.deb && sudo dpkg -i cosfs_1.0.25-ubuntu24.04_amd64.deb

与 s3fs 相比，使用 cosfs 时需要注意以下差异:

存储桶名称需要带 APPID 后缀，格式为 bucketname-appid，例如 mybucket-1250000000。
凭据写入 /etc/passwd-cosfs。
挂载时通过 -ourl 参数指定 COS 的访问端点，例如 https://cos.ap-beijing.myqcloud.com。

以下实现演示了如何使用 cosfs-fuse 模板在 Sandbox 环境中以编程方式挂载腾讯云 COS 存储桶:

import os
import time

from ppio_sandbox import PPIO

ppio = PPIO()

# 腾讯云 COS 配置
SECRET_ID = os.environ.get('TENCENT_SECRET_ID')
SECRET_KEY = os.environ.get('TENCENT_SECRET_KEY')
BUCKET_NAME = os.environ.get('COS_BUCKET_NAME')  # 格式: bucketname-appid，例如 mybucket-1250000000
REGION = os.environ.get('COS_REGION')  # 例如 ap-beijing

if not SECRET_ID or not SECRET_KEY or not BUCKET_NAME or not REGION:
    raise ValueError(
        'Required environment variables not configured: TENCENT_SECRET_ID, TENCENT_SECRET_KEY, COS_BUCKET_NAME, COS_REGION')

MOUNT_DIRECTORY = '/mnt/cos-bucket'

sandbox = ppio.sandbox.create("cosfs-fuse")
print(f'Sandbox id: {sandbox.sandbox_id}')

# 初始化挂载目录
sandbox.files.make_dir(MOUNT_DIRECTORY)

# 写入腾讯云凭据（格式与 s3fs 一致: BucketName-APPID:SecretId:SecretKey）
sandbox.files.write('/etc/passwd-cosfs', f'{BUCKET_NAME}:{SECRET_ID}:{SECRET_KEY}')

# 设置凭据文件权限
sandbox.commands.run('sudo chmod 640 /etc/passwd-cosfs')

# 挂载 COS bucket，-ourl 指定 COS 访问端点
# 参考：https://github.com/tencentyun/cosfs
sandbox.commands.run(
    f'sudo cosfs -f {BUCKET_NAME} {MOUNT_DIRECTORY} -ourl=https://cos.{REGION}.myqcloud.com -odbglevel=info -oallow_other',
    background=True)

# 等待挂载就绪，你也可以构建一个template，让挂载指令随系统启动时生效
time.sleep(3)

# 验证写入
sandbox.files.write(f'{MOUNT_DIRECTORY}/test-file.txt', 'test-file-content')

# 验证读取，这时也可以查看 bucket 的后台看下是否存在该文件
content = sandbox.files.read(f'{MOUNT_DIRECTORY}/test-file.txt')
print('File content:', content)

sandbox.kill()

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// 腾讯云 COS 配置
const SECRET_ID = process.env.TENCENT_SECRET_ID
const SECRET_KEY = process.env.TENCENT_SECRET_KEY
const BUCKET_NAME = process.env.COS_BUCKET_NAME // 格式: bucketname-appid，例如 mybucket-1250000000
const REGION = process.env.COS_REGION // 例如 ap-beijing
if (!SECRET_ID || !SECRET_KEY || !BUCKET_NAME || !REGION) {
  throw new Error('Required environment variables not configured: TENCENT_SECRET_ID, TENCENT_SECRET_KEY, COS_BUCKET_NAME, COS_REGION')
}

const MOUNT_DIRECTORY = '/mnt/cos-bucket'

const sandbox = await ppio.sandbox.create("cosfs-fuse")
console.log(`Sandbox id: ${sandbox.sandboxId}`)

// 初始化挂载目录
await sandbox.files.makeDir(MOUNT_DIRECTORY)

// 写入腾讯云凭据（格式与 s3fs 一致: BucketName-APPID:SecretId:SecretKey）
await sandbox.files.write('/etc/passwd-cosfs', `${BUCKET_NAME}:${SECRET_ID}:${SECRET_KEY}`)

// 设置凭据文件权限
await sandbox.commands.run('sudo chmod 640 /etc/passwd-cosfs')

// 挂载 COS bucket，-ourl 指定 COS 访问端点
// 参考：https://github.com/tencentyun/cosfs
await sandbox.commands.run(
  `sudo cosfs -f ${BUCKET_NAME} ${MOUNT_DIRECTORY} -ourl=https://cos.${REGION}.myqcloud.com -odbglevel=info -oallow_other`,
  { background: true },
)

// 等待挂载就绪，你也可以构建一个template，让挂载指令随系统启动时生效
const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
await sleep(3000)

// 验证写入
await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

// 验证读取，这时也可以查看 bucket 的后台看下是否存在该文件
const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
console.log('File content:', content)

await sandbox.kill()

阿里云 OSS

使用 ossfs 2.0（阿里云新一代基于 FUSE 的文件系统客户端），可以将阿里云 OSS 存储桶挂载为 POSIX 兼容的文件系统。我们同样提供了 PPIO 官方模板 ossfs-fuse，其中已预装 ossfs2；你也可以在自定义 Template 的 ppio.Dockerfile 中自行安装，或在运行中的 Sandbox 实例内按需动态安装。 模板 Dockerfile 构建：

FROM ubuntu:latest

RUN sudo curl -o ossfs2_2.0.8_linux_x86_64.deb https://gosspublic.alicdn.com/ossfs/ossfs2_2.0.8_linux_x86_64.deb && sudo dpkg -i ossfs2_2.0.8_linux_x86_64.deb

与 s3fs 相比，使用 ossfs2 时需要注意以下差异:

挂载配置（endpoint、bucket、AccessKey）统一写入配置文件 /etc/ossfs2.conf，而不是通过命令行参数传入，并需将该文件权限设置为 640。
OSS 访问端点格式为 https://oss-{region}.aliyuncs.com，例如 https://oss-cn-hangzhou.aliyuncs.com。
挂载命令为 ossfs2 mount <挂载目录> -c <配置文件>。

以下实现演示了如何使用 ossfs-fuse 模板在 Sandbox 环境中以编程方式挂载阿里云 OSS 存储桶:

import os
import time

from ppio_sandbox import PPIO

ppio = PPIO()

# 阿里云 OSS 配置
SECRET_ID = os.environ.get('OSS_SECRET_ID')
SECRET_KEY = os.environ.get('OSS_SECRET_KEY')
BUCKET_NAME = os.environ.get('OSS_BUCKET_NAME')
REGION = os.environ.get('OSS_REGION')  # 例如 cn-hangzhou

if not SECRET_ID or not SECRET_KEY or not BUCKET_NAME or not REGION:
    raise ValueError(
        'Required environment variables not configured: OSS_SECRET_ID, OSS_SECRET_KEY, OSS_BUCKET_NAME, OSS_REGION')

MOUNT_DIRECTORY = '/mnt/oss-bucket'

sandbox = ppio.sandbox.create("ossfs-fuse", envs={
    "OSS_ACCESS_KEY_ID": SECRET_ID,
    "OSS_ACCESS_KEY_SECRET": SECRET_KEY,
})
print(f'Sandbox id: {sandbox.sandbox_id}')

# 初始化挂载目录
sandbox.files.make_dir(MOUNT_DIRECTORY)

# 写入阿里云 ossfs 配置
sandbox.files.write('/etc/ossfs2.conf', f"""--oss_endpoint=https://oss-{REGION}.aliyuncs.com
--oss_bucket={BUCKET_NAME}
--oss_access_key_id={SECRET_ID}
--oss_access_key_secret={SECRET_KEY}
""")

# 设置配置文件权限
sandbox.commands.run('sudo chmod 640 /etc/ossfs2.conf')

# 挂载 OSS bucket
# 参考：https://github.com/aliyun/ossfs2
sandbox.commands.run(
    f'sudo ossfs2 mount {MOUNT_DIRECTORY} -c /etc/ossfs2.conf',
    background=True)

# 等待挂载就绪，你也可以构建一个template，让挂载指令随系统启动时生效
time.sleep(3)

# 验证写入
sandbox.files.write(f'{MOUNT_DIRECTORY}/test-file.txt', 'test-file-content')

# 验证读取，这时也可以查看 bucket 的后台看下是否存在该文件
content = sandbox.files.read(f'{MOUNT_DIRECTORY}/test-file.txt')
print('File content:', content)

sandbox.kill()

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// 阿里云 OSS 配置
const SECRET_ID = process.env.OSS_SECRET_ID
const SECRET_KEY = process.env.OSS_SECRET_KEY
const BUCKET_NAME = process.env.OSS_BUCKET_NAME
const REGION = process.env.OSS_REGION // 例如 cn-hangzhou
if (!SECRET_ID || !SECRET_KEY || !BUCKET_NAME || !REGION) {
  throw new Error('Required environment variables not configured: OSS_SECRET_ID, OSS_SECRET_KEY, OSS_BUCKET_NAME, OSS_REGION')
}

const MOUNT_DIRECTORY = '/mnt/oss-bucket'

const sandbox = await ppio.sandbox.create('ossfs-fuse', {
  envs: {
    OSS_ACCESS_KEY_ID: SECRET_ID,
    OSS_ACCESS_KEY_SECRET: SECRET_KEY,
  },
})
console.log(`Sandbox id: ${sandbox.sandboxId}`)

// 初始化挂载目录
await sandbox.files.makeDir(MOUNT_DIRECTORY)

// 写入阿里云 ossfs 配置
await sandbox.files.write('/etc/ossfs2.conf', `--oss_endpoint=https://oss-${REGION}.aliyuncs.com
--oss_bucket=${BUCKET_NAME}
--oss_access_key_id=${SECRET_ID}
--oss_access_key_secret=${SECRET_KEY}
`)

// 设置配置文件权限
await sandbox.commands.run('sudo chmod 640 /etc/ossfs2.conf')

// 挂载 OSS bucket
// 参考：https://github.com/aliyun/ossfs2
await sandbox.commands.run(
  `sudo ossfs2 mount ${MOUNT_DIRECTORY} -c /etc/ossfs2.conf`,
  { background: true },
)

// 等待挂载就绪，你也可以构建一个template，让挂载指令随系统启动时生效
await sleep(3000)

// 验证写入
await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

// 验证读取，这时也可以查看 bucket 的后台看下是否存在该文件
const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
console.log('File content:', content)

await sandbox.kill()

产品简介

快速开始

最佳实践

Sandbox

Template

Snapshot

文件系统

Secret

Volume

工具集成

CLI 功能

旧版归档

Amazon S3

腾讯云 COS

阿里云 OSS

​Amazon S3

​腾讯云 COS

​阿里云 OSS

Amazon S3

腾讯云 COS

阿里云 OSS