# التخزين

> تخزين كائنات متوافق مع S3 على تاروت

# التخزين

توفر تاروت تخزين كائنات للملفات والصور والنسخ الاحتياطية والأصول الثابتة. وتصل إليه التطبيقات عبر بوابة متوافقة مع S3 تدعم عمليات الكائنات الأساسية (راجع قسم «ما تدعمه بوابة S3» أدناه).

## إنشاء حاوية تخزين

1. انتقل إلى **التخزين** في لوحة التحكم.
2. انقر **حاوية جديدة**.
3. أدخل اسم الحاوية (اختياري، وتولّد تاروت اسمًا إن تركته فارغًا) ووصفًا اختياريًا.
4. اترك **الوصول العام** معطّلًا ما لم يكن مطلوبًا أن يقرأ أي شخص على الإنترنت الملفات.
5. انقر **إنشاء**.

لا تختار خطة تخزين لكل حاوية، فالحاوية تتبع اشتراكك:

- **الخطة المجانية** - حاوية واحدة بمساحة 50 ميجابايت.
- **الخطط المدفوعة** - حتى 3 حاويات لكل مشروع، تتشارك سعة التخزين التي تضيفها إلى خطتك بسعر 0.12 ريال لكل جيجابايت شهريًا. أضف السعة قبل إنشاء حاوية مدفوعة.

من سطر الأوامر: `tarout storage create [name]` (أضف `--public` لحاوية عامة).

## رفع الملفات

### لوحة التحكم وسطر الأوامر

اسحب وأفلت الملفات في صفحة تفاصيل الحاوية، أو انقر **رفع** لاختيار الملفات. ومن الطرفية استخدم `tarout storage put <bucket> <key> <file>`. كلا الطريقتين ترسل الملف مباشرةً إلى التخزين عبر رابط رفع موقّع، لذا استخدمهما للملفات الكبيرة.

### من تطبيقك على تاروت

اربط الحاوية بالتطبيق، إما من صفحة الحاوية في لوحة التحكم أو من سطر الأوامر. تنشئ تاروت مفتاح وصول مقيّدًا بتلك الحاوية وذلك التطبيق، وتضيف بيانات الاتصال إلى متغيرات بيئة التطبيق:

```bash
tarout storage attach <bucket> <app-id>
```

يجب أن تكون الحاوية والتطبيق في المشروع نفسه. ويقوم `tarout deploy` بهذا نيابةً عنك عندما ينشئ حاوية لمشروعك. وإذا كان التطبيق منشورًا، فإن الربط يعيد تشغيله لتسري المتغيرات.

يضبط الربط هذه المتغيرات (ضمن غيرها):

| المتغير | القيمة |
|---|---|
| `STORAGE_ENDPOINT` | عنوان بوابة S3 |
| `STORAGE_BUCKET` | اسم الحاوية المستخدم في طلبات S3 |
| `STORAGE_REGION` | `auto` |
| `STORAGE_ACCESS_KEY_ID` | مفتاح الوصول الخاص بهذا التطبيق |
| `STORAGE_SECRET_ACCESS_KEY` | السر الخاص بذلك المفتاح |

وتُضبط القيم نفسها أيضًا بالأسماء التي تقرؤها مكتبات كثيرة افتراضيًا: `S3_ENDPOINT` و`S3_BUCKET` و`AWS_ACCESS_KEY_ID` و`AWS_SECRET_ACCESS_KEY` و`AWS_ENDPOINT_URL` و`AWS_REGION` و`AWS_S3_FORCE_PATH_STYLE=true`.

### AWS SDK (متوافق مع S3)

```javascript
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: process.env.STORAGE_ENDPOINT,
  region: process.env.STORAGE_REGION ?? "auto",
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.STORAGE_ACCESS_KEY_ID,
    secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY,
  },
});

await s3.send(
  new PutObjectCommand({
    Bucket: process.env.STORAGE_BUCKET,
    Key: "uploads/photo.jpg",
    Body: fileBuffer,
  })
);
```

الخيار `forcePathStyle: true` مطلوب، لأن البوابة تتوقع اسم الحاوية في مسار الرابط لا في اسم النطاق. واستخدم دائمًا `STORAGE_BUCKET` اسمًا للحاوية، لا الاسم الظاهر الذي كتبته في لوحة التحكم.

### من خارج تاروت

للخوادم أو الأدوات التي لا تعمل على تاروت، أنشئ مفتاحًا من قسم **مفاتيح الوصول** في الحاوية. لا تعمل هذه المفاتيح إلا بعد تفعيل إعداد **الوصول الخارجي** للحاوية وإضافة عناوين IP (أو نطاقات CIDR) المسموح لها بالاتصال. ومن سطر الأوامر:

```bash
tarout storage external-access <bucket> --enable --cidrs 203.0.113.10/32
```

تُرفض الطلبات القادمة من أي عنوان آخر حتى مع مفتاح صالح. أما المفاتيح التي تُنشأ بربط الحاوية بتطبيق على تاروت فلا تحتاج هذا الإعداد. واستخدم معرّف الحاوية اسمًا لها في طلبات S3 من خارج تاروت.

## ما تدعمه بوابة S3

- رفع كائن واحد (`PUT`) وتنزيله (`GET`) وقراءة بياناته (`HEAD`) وحذفه (`DELETE`).
- عرض محتويات الحاوية (`GET` على الحاوية)، مع إمكانية التصفية ببادئة. تعيد القائمة أول 1,000 مفتاح كحد أقصى.
- **لا يوجد رفع متعدد الأجزاء.** يُرسل كل كائن في طلب `PUT` واحد. للملفات الكبيرة، ارفعها من لوحة التحكم أو بالأمر `tarout storage put` بدل طلب واحد ضخم عبر البوابة.
- **لا توجد طلبات Range.** يعيد `GET` الكائن كاملًا دائمًا.

الأدوات التي تنتقل إلى الرفع متعدد الأجزاء للملفات الكبيرة (مثل `aws s3 cp` أو `rclone` فوق حد الحجم لديها) تحتاج إلى تعطيل ذلك أو رفع الحد.

## التحكم بالوصول

- الملفات خاصة افتراضياً ومتاحة عبر روابط موقّعة أو بيانات اعتماد صالحة ومقيدة بالحاوية.
- الحاوية التي فُعّل فيها **الوصول العام** تسمح لأي شخص بقراءة ملفاتها عبر بوابة التخزين دون بيانات اعتماد. أما الرفع والحذف فيتطلبان مفتاحًا دائمًا.

## حالات الاستخدام

- **رفعيات المستخدمين** - صور الملفات الشخصية، المستندات، المرفقات.
- **الأصول الثابتة** - الصور، CSS، JavaScript.
- **النسخ الاحتياطية** - نسخ قواعد البيانات، لقطات التطبيقات.
- **الوسائط** - تخزين الفيديو والصوت والملفات الكبيرة.

## التسعير

يُحاسب التخزين المدفوع على السعة التي تحجزها لا على ما تستخدمه فعليًا: 0.12 ريال لكل جيجابايت شهريًا، وتتشارك هذه السعة جميع حاويات المشروع. وتشمل الخطة المجانية حاوية واحدة بمساحة 50 ميجابايت. راجع قسم [الفوترة](https://tarout.sa/docs/billing) للأسعار الحالية.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md