# TOS (火山对象存储) Node.js SDK 集成

## 📦 安装依赖

在您的 jimeng-free-api 项目中安装以下依赖：

```bash
# 安装火山对象存储 JS SDK
npm install @volcengine/tos-sdk

# 安装其他必需的依赖
npm install axios mime-types

# 安装 TypeScript 类型定义
npm install --save-dev @types/node @types/mime-types typescript

# 可选：安装开发工具
npm install --save-dev ts-node ts-node-dev
```

## 📁 项目结构

将以下文件复制到您的 `src/lib/` 目录中：

```
src/lib/
├── util.ts                 # 现有的工具文件
├── tos-client.ts          # TOS 客户端封装类
├── tos-service.ts         # TOS 服务类和使用示例
└── tos-test.ts            # TOS 功能测试文件（可选）
```

## 环境变量配置

在您的 `.env` 文件中添加以下配置：

```env
# 火山对象存储配置
TOS_ACCESS_KEY_ID=your_access_key_id
TOS_ACCESS_KEY_SECRET=your_access_key_secret
TOS_BUCKET_NAME=your_bucket_name
TOS_SELF_DOMAIN=your_custom_domain.com
```

## 使用方法

### 1. 基础配置

```typescript
import { TOSClientWrapper, TOSClientConfig } from './tos-client';

const config: TOSClientConfig = {
  accessKeyId: process.env.TOS_ACCESS_KEY_ID!,
  accessKeySecret: process.env.TOS_ACCESS_KEY_SECRET!,
  endpoint: 'tos-cn-beijing.volces.com',
  region: 'cn-beijing',
  bucketName: process.env.TOS_BUCKET_NAME!,
  selfDomain: process.env.TOS_SELF_DOMAIN!
};

const tosClient = new TOSClientWrapper(config);
```

### 2. 快速使用服务类

```typescript
import TOSService from './tos-service';

// 上传文本
const textUrl = await TOSService.uploadText('Hello World', 'test.txt');

// 上传本地文件
const fileUrl = await TOSService.uploadLocalFile('/path/to/file.jpg');

// 从URL上传
const urlResult = await TOSService.uploadFromUrl('https://example.com/image.jpg');

// 上传Buffer
const buffer = Buffer.from('data');
const bufferUrl = await TOSService.uploadBuffer(buffer, 'file.txt', 'text/plain');
```

### 3. 直接使用客户端

```typescript
import { TOSClientWrapper } from './tos-client';

const client = new TOSClientWrapper(config);

// 上传字符串
await client.uploadString('content', 'path/file.txt');

// 上传文件
await client.uploadFile('./local-file.jpg', 'uploads/image.jpg');

// 下载文件
const data = await client.downloadFile('uploads/image.jpg');

// 删除文件
await client.deleteFile('uploads/image.jpg');
```

## API 对照表

以下是 Python 版本和 TypeScript 版本的 API 对照：

| Python 方法 | TypeScript 方法 | 说明 |
|-------------|----------------|------|
| `upload_string()` | `uploadString()` | 上传字符串内容 |
| `upload_file()` | `uploadFile()` | 上传本地文件 |
| `upload_bytes()` | `uploadBytes()` | 上传字节数据 |
| `upload_from_url()` | `uploadFromUrl()` | 从URL上传文件 |
| `download_file()` | `downloadFile()` | 下载文件 |
| `delete_file()` | `deleteFile()` | 删除文件 |
| `generate_url()` | `generateUrl()` | 生成签名URL |
| `get_base_url()` | `getBaseUrl()` | 获取基础URL |

## 特性

✅ 支持字符串上传  
✅ 支持本地文件上传  
✅ 支持从URL上传文件  
✅ 支持Buffer数据上传  
✅ 支持文件下载  
✅ 支持文件删除  
✅ 支持生成签名URL  
✅ 支持检查文件存在性  
✅ 支持获取文件信息  
✅ 支持列出存储桶对象  
✅ 自动Content-Type检测  
✅ 错误处理和重试机制  
✅ TypeScript 类型支持  

## 注意事项

1. 确保您的火山对象存储账户已正确配置
2. 自定义域名需要在火山控制台中配置
3. 生产环境中请妥善保管访问密钥
4. 建议在生产环境中启用HTTPS
5. 大文件上传建议使用分片上传（可根据需要扩展）

## 🔧 故障排除

### 问题 1：找不到模块 '@volcengine/tos-sdk'

**解决方案：**
```bash
npm install @volcengine/tos-sdk
# 或
yarn add @volcengine/tos-sdk
```

### 问题 2：找不到名称 'process' 或 'Buffer'

**解决方案：**
```bash
npm install --save-dev @types/node
```

### 问题 3：编译错误

**检查 tsconfig.json 配置：**
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "types": ["node"],
    "esModuleInterop": true,
    "moduleResolution": "node"
  }
}
```

### 问题 4：SSL 警告

**如果遇到 SSL 警告，可以：**
1. 设置 `disableSSLWarnings: true`
2. 或者使用正确的 SSL 证书

### 问题 5：上传失败

**检查以下配置：**
1. AccessKey 和 SecretKey 是否正确
2. Bucket 名称是否正确
3. Region 是否匹配
4. 网络连接是否正常
5. 权限是否足够

### 问题 6：自定义域名访问失败

**检查：**
1. 域名 DNS 解析是否正确
2. 域名是否已在火山控制台绑定
3. HTTPS 证书是否有效

## 🎆 快速测试

**创建测试文件：**
```typescript
// test-quick.ts
import TOSService from './tos-service';

async function quickTest() {
  try {
    // 测试上传文本
    const result = await TOSService.uploadText('你好，TOS！', 'hello.txt');
    console.log('上传成功:', result);
  } catch (error) {
    console.error('测试失败:', error.message);
  }
}

quickTest();
```

**运行测试：**
```bash
# 使用 ts-node 直接运行
ts-node test-quick.ts

# 或编译后运行
tsc test-quick.ts
node test-quick.js
```

## 错误处理

所有方法都包含完善的错误处理，会抛出带有详细信息的错误：

```typescript
try {
  const result = await TOSService.uploadFile('/path/to/file.jpg');
  console.log('上传成功:', result);
} catch (error) {
  console.error('上传失败:', error.message);
}
```