# البيئات

> احتفظ بملفات .env ومتغيرات البيئة في الخزنة، وسلّمها إلى Docker وCI وNode وPython وصدفات الأوامر العادية، وحمّلها في صدفتك وأنت تنتقل بين المشاريع.

Source: https://octap.app/ar/docs/features/environments/
Status: in-progress
Project: Octa Pass

:::note[قيد التطوير]
البيئات تعمل في خزنة الويب وإضافة المتصفح وواجهة سطر الأوامر وتطبيقات iPhone وiPad وAndroid الأصلية. يعيد تطبيق سطح المكتب استخدام شاشات خزنة الويب عند صدوره. وعلى الهاتف تستطيع قراءة البيئات وتحريرها وتصفيتها ونسخها وحفظها؛ أما تشغيل أمر بها فمهمة واجهة سطر الأوامر.
:::

**البيئة** هي متغير واحد (`API_KEY`) أو ملف `.env` كامل محفوظ كعنصر في خزنتك. تُشفَّر القيم على جهازك مثل كلمات المرور، فلا يراها الخادم أبدًا، ولا تسلّمها واجهة سطر الأوامر إلا للأمر الذي تشغّله أو للملف الذي تطلبه. يمكن لبيئة واحدة أن تحمل الإعدادات المشتركة لمشروع، ولأخرى أن تحمل قيم `production`، فتعمل الأدوات نفسها في كل مرحلة.

## ما الذي تحمله البيئة

| الحقل | ملاحظات |
|---|---|
| **العنوان** | مثل `Shop API (production)`. |
| **المشروع** | معرّف قصير مثل `shop-api` يجمع مراحل تطبيق واحد. اختياري. |
| **المرحلة** | `development` أو `staging` أو `production` أو `testing` أو `preview` أو `local`، أو اسم من عندك. اختياري. |
| **المتغيرات** | قائمة مرتبة من `KEY` والقيمة وعلامة **الإخفاء** (مفعّلة افتراضيًا) وملاحظة اختيارية. يُحفظ الترتيب عند كتابة البيئة في ملف. |
| **الملاحظات** | مثل أي عنصر. |

اسم المتغير حروف وأرقام و`_`، ولا يجوز أن يبدأ برقم. يُستخدم كل اسم مرة واحدة في البيئة؛ ويبيّن المحرر و`env set` أيّ الأسماء خاطئ. والمتغير المنفرد هو ببساطة بيئة بمدخل واحد.

يمكن أن تكون القيمة [مرجعًا](#المراجع) بالصيغة `octapass://<vault>/<item>/<field>`، مثل كلمة مرور بيانات دخول. لا يُحلّ المرجع إلا عند استخدام البيئة (`run` أو `export` أو الخطّاف)، ولا تُكتب القيمة المحلولة مرة أخرى في الخزنة أبدًا.

## المشاريع والمراحل

البيئة التي لها مشروع وبلا مرحلة هي المجموعة **المشتركة** لذلك المشروع. وعند تحميل مشروع ومرحلة معًا، تُطبَّق المتغيرات المشتركة أولًا ثم تتجاوزها متغيرات المرحلة:

| الترتيب | ما هو |
|---|---|
| 1 | بيئة المشروع المشتركة (بلا مرحلة) |
| 2 | بيئة المرحلة |
| 3 | بيئات أخرى مسمّاة في سطر الأوامر أو في `octapass.toml`، بالترتيب |
| 4 | ملفات `--env-file`، بالترتيب |
| 5 | المراجع في البيئة الناتجة |

القيم اللاحقة تغلب، فاسم مضبوط في `staging` يتجاوز القيمة المشتركة، وبيئة مسمّاة بعدها تتجاوزهما معًا. يبيّن `octapass env diff` أيّ الأسماء ناقص من أحد الجانبين أو له قيم مختلفة، دون طباعة أي من القيمتين.

## في خزنة الويب والإضافة

للبيئات فئتها الخاصة وقسمها الخاص حين تُجمَّع القائمة بحسب النوع. تجمّعها القائمة بحسب المشروع، وتعرض **شارة المرحلة** على كل منها، وتُرشَّح بحسب المشروع والمرحلة؛ وعنصر المرحلة يذكر أيضًا أي المفاتيح موجودة في مراحل المشروع الأخرى وغير موجودة في هذه. يجد البحث البيئة بعنوانها وأسماء متغيراتها، لا بقيمها أبدًا.

المحرر جدول: أضف المتغيرات وأزلها وأعد ترتيبها وأخفِها، وأضف ملاحظة، واضبط المشروع والمرحلة، والصق ملف `.env` أو استورده دفعة واحدة. في وضع العرض لكل متغير زر إظهار ونسخ خاص به، ويعمل **نسخ بصيغة ‎.env** و**تنزيل ‎.env** على المجموعة كلها، بما فيها القيم المخفية. ويسرد تبويب Octa Pass في إضافة المتصفح البيئات مع أنواع العناصر الأخرى وتفتحها في العرض نفسه.

العربية مترجمة لكل نص جديد، مثل بقية خزنة الويب والإضافة.

## على الحاسوب

تقرأ واجهة سطر الأوامر العناصر نفسها. الملفات التي تكتبها قابلة للقراءة لك وحدك (الوضع `0600`؛ وعلى Windows تُستبدل الأذونات الموروثة بمدخل واحد لمستخدمك)، ولا تُستبدل أبدًا دون `--force`.

| الأمر | ما يفعله |
|---|---|
| `octapass env list [--vault V] [--project P]` | يسرد البيئات، مجمّعة بحسب المشروع، مع مراحلها وعدد المتغيرات. لا يطبع القيم أبدًا. |
| `octapass env show <env> [--reveal]` | يعرض المتغيرات. تبقى القيم المخفية مخفية دون `--reveal`. |
| `octapass env set <env> KEY=value… [--plain]` | يضيف المتغيرات أو يغيّرها. `KEY` وحده يطلب القيمة دون إظهارها؛ و`--plain` يترك القيم ظاهرة في القوائم. |
| `octapass env unset <env> KEY…` | يزيل المتغيرات. |
| `octapass env create <title> [--vault V] [--project P] [--stage S]` | ينشئ بيئة فارغة. |
| `octapass env import <file> --into <env>` | يقرأ ملف `.env` إلى بيئة موجودة، ويستبدل الأسماء الموجودة فيها أصلًا. |
| `octapass env import <file> --new <title> [--project P] [--stage S]` | ينشئ بيئة من ملف `.env`. |
| `octapass env export <env> [--format dotenv\|json\|shell\|powershell\|docker] [-o FILE] [--force] [--keep-references]` | يكتب المتغيرات إلى الخرج القياسي أو إلى ملف. |
| `octapass env diff <project> <stage> <stage>` أو `octapass env diff <env> <env>` | يسرد الأسماء الناقصة والمختلفة، دون القيم. |
| `octapass run --env <env> [--env <env>] … -- <command>` | يشغّل أمرًا مع تطبيق البيئات وأي مراجع `octapass://`. |
| `octapass run --project P --stage S -- <command>` | يحمّل المجموعة المشتركة للمشروع ومرحلته المحددة، ثم يشغّل. |
| `octapass inject -i template -o out [--force]` | يستبدل مراجع `octapass://` في أي ملف نصي. |
| `octapass env hook zsh\|bash\|fish\|powershell` | يطبع خطّاف صدفة يحمّل بيئة المجلد وأنت تنتقل إليه بـ `cd`. |
| `octapass env allow [path]` / `octapass env deny [path]` | يسمح بالخطّاف لملف `octapass.toml` في مجلد أو يوقفه. |

يمكن تسمية البيئة بعنوانها (بأي حالة أحرف) أو معرّفها أو `vault/title` أو `project:stage` (و`project:` وحدها هي المجموعة المشتركة). يعمل `--json` مثل بقية الأوامر. راجع [مرجع واجهة سطر الأوامر](https://octap.app/ar/docs/platforms/cli/#البيئات) للتفاصيل ورموز الخروج.

### المراجع

يمكن أن تشير قيمة المتغير كلها إلى حقل في عنصر آخر:

```bash
octapass env set "Shop API (production)" DB_PASSWORD=octapass://Personal/Postgres/password
octapass run --env "Shop API (production)" -- ./migrate.sh
```

يكتب `octapass env export` القيمة المحلولة؛ و`--keep-references` يكتب المرجع كما هو. يُتبَع المرجع خطوة واحدة: إذا كانت القيمة التي يشير إليها مرجعًا هي نفسها، يتوقف `run` بخطأ واضح بدل أن يدور في حلقة. ويقرأ `octapass://<vault>/<item>/<KEY>` أيضًا متغيرًا من عنصر بيئة مباشرة، فيمكن لملف إعداد أن يشير إلى متغير واحد بدل عنصر كامل.

### ملف المشروع

ضع `octapass.toml` في مستودع (تبحث واجهة سطر الأوامر في المجلد الحالي ومجلداته الأعلى، حتى جذر المستودع) لتحدد ما يحمّله `octapass run` وخطّاف الصدفة افتراضيًا:

```toml
project = "shop-api"
stage = "development"
env = ["Personal/Shop API extras"]
vault = "Personal"
```

`--env` و`--project` و`--stage` في سطر الأوامر تتجاوزه. و`OCTAPASS_STAGE` يتجاوز مرحلة الملف دون تعديله، وهذا مفيد في CI.

:::caution[الإنتاج يسأل أولًا]
تحميل مرحلة `production` لم تسمِّها صراحةً يطلب تأكيدًا. مرّر `--stage production` (أو `--env shop-api:production`) لتقول إنك تقصدها، أو `--yes` للنصوص البرمجية. ويسأل خطّاف الصدفة بالطريقة نفسها، ويرفض حين لا تتوفر له طرفية؛ ولا يسأل عن كلمة مرورك الرئيسية أبدًا.
:::

### خطّاف الصدفة

يطبع `octapass env hook zsh` (أو `bash` أو `fish` أو `powershell`) الشيفرة لملف بدء صدفتك:

```bash
eval "$(octapass env hook zsh)"
```

عند كل موجّه أوامر، في مجلد فيه `octapass.toml` سمحت به مرة واحدة بـ `octapass env allow`، يحمّل الخطّاف بيئة المشروع ويفرغها عند مغادرتك المجلد، أو عند تغيّر الملف، أو عند قفل Octa Pass. لا يُحمَّل شيء وواجهة سطر الأوامر مقفلة، ولا يسأل الخطّاف أبدًا عن كلمة المرور الرئيسية: شغّل `octapass unlock` أولًا. وتُحفظ قائمة المسموح به في مجلد بيانات واجهة سطر الأوامر ومفتاحها مسار الملف ومحتواه، فتعديل `octapass.toml` يسأل من جديد، كما يفعل [direnv](https://direnv.net).

يضبط الخطّاف المتغيرات في صدفتك طوال مدة وجودك في المشروع فقط. ولا يكتب Octa Pass الأسرار أبدًا في بيئة النظام الدائمة (`setx` أو `/etc/environment` أو `launchctl setenv` أو ملفات بدء صدفتك): ستبقى هناك بنص صريح أمام كل برنامج. استخدم `run` أو الخطّاف أو ملفًا يُحذف بعد ذلك.

## Docker

مع Compose، دع الصدفة أو `octapass run` يوفّران المتغيرات لاستبدال `${KEY}`:

```bash
octapass run --env "Shop API (development)" -- docker compose up
```

```yaml
services:
  api:
    image: shop-api
    environment:
      - DATABASE_URL
      - LOG_LEVEL
```

أو اكتب ملفًا لإعداد `env_file:`. يكتب `--env-file-out` البيئة إلى ملف قابل للقراءة لك وحدك طوال تشغيل الأمر، ثم يحذفه، بما في ذلك حين تضغط Ctrl-C:

```bash
octapass run --project shop-api --stage development \
  --env-file-out .env -- docker compose up
```

لحاوية واحدة، يقرأ `docker run --env-file` ملفًا عاديًا بصيغة `KEY=value`:

```bash
docker run --env-file <(octapass env export "Shop API (development)" --format docker) shop-api
```

استبدال العملية هذا مخصص لـ bash وzsh على macOS وLinux؛ أما PowerShell و`cmd` فيحتاجان إلى ملف مؤقت (و`--format docker` يرفض القيم متعددة الأسطر، لأن صيغة Docker لا تعرف علامات الاقتباس).

لا ينبغي أن تصبح أسرار وقت البناء طبقات في الصورة. مرّرها كأسرار BuildKit، وليس أبدًا كـ `ARG` أو `ENV`:

```bash
octapass run --env "Shop API (development)" -- \
  docker build --secret id=npm_token,env=NPM_TOKEN .
```

```dockerfile
# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
```

قيمة `ARG` أو `ENV` تبقى في سجل الصورة ويقرؤها كل من يسحبها، حتى لو أزالتها طبقة لاحقة.

## CI

مشغّلات CI غير تفاعلية، لذلك أعطِ واجهة سطر الأوامر كلمة المرور الرئيسية والمفتاح السري عبر مخزن أسرار المشغّل، ثم استخدم `run` في الخطوات التي تحتاج إلى أسرار:

```bash
printf '%s\n' "$OCTAPASS_PASSWORD" | octapass --password-stdin login --server "$OCTAPASS_SERVER"
octapass run --project shop-api --stage testing --yes -- npm test
```

يوفّر `OCTAPASS_SECRET_KEY` المفتاح السري عند أول تسجيل دخول بلا طرفية، ويوفّر `OCTAPASS_TWO_STEP_CODE` رمز الخطوتين. تبقى الجلسة في حلقة مفاتيح المشغّل (أو في مجلد البيانات مع `OCTAPASS_NO_KEYRING=1`، الذي لا يحتفظ بكلمة المرور الرئيسية). علّم المتغيرات كأسرار في نظام CI، ولا تطبعها ولا تمرّرها إلى `docker build` كوسائط بناء. يتخطى `--yes` تأكيد الإنتاج لمرحلة `production` مسمّاة؛ لا تستخدمه إلا حيث يُقصد من المهمة أن تمس الإنتاج.

## Node وPython وصدفات الأوامر العادية

تقرأ Node القيم من `process.env` وPython من `os.environ`، فيكفي `run`:

```bash
octapass run --project shop-api -- npm start
octapass run --env "Shop API (testing)" -- python manage.py migrate
```

الأدوات التي تقرأ ملف `.env` فقط يمكنها الحصول على واحد طوال مدة عملها:

```bash
octapass run --env "Shop API (development)" --env-file-out .env.local -- next dev
```

تستطيع صدفة عادية تحميل بيئة لأمر واحد أو للجلسة، دون كتابتها على القرص:

```bash
eval "$(octapass env export "Shop API (development)" --format shell)"
```

تبقى المتغيرات في تلك الصدفة حتى تغلقها أو تلغي ضبطها؛ أما `octapass run --env … --` فيحصرها في الأمر.

يكتب `--format shell` أسطر `export KEY='value'` لـ sh وbash وzsh، ويكتب `--format powershell` أسطر `$env:KEY = 'value'`:

```powershell
octapass env export "Shop API (development)" --format powershell | Out-String | Invoke-Expression
```

الفروق على Windows: الملفات التي تكتبها واجهة سطر الأوامر تستخدم ACL لمالك واحد بدل بتات أذونات Unix؛ وPowerShell هي صيغة الصدفة الأصلية؛ ويُثبَّت الخطّاف في ملف تعريف PowerShell الخاص بك؛ واستبدال العملية غير متاح، فاكتب `--env-file-out` أو ملف تصدير لـ Docker. وما عدا ذلك تتصرف Docker Desktop وWSL وGit Bash مثل نظيراتها على Linux.

## الاستيراد والتصدير والنسخ الاحتياطية

- **الاستيراد:** ملف `.env` في المحرر (بلصقه أو اختيار ملف) أو بـ `octapass env import`. تُفهم تعليقات `#` وكلمة `export ` الاختيارية؛ وتُحفظ القيم متعددة الأسطر بين علامتي اقتباس مزدوجتين (مثل مفاتيح PEM)؛ والاسم المستخدم مرتين خطأ يذكر السطر.
- **التصدير:** `.env` (dotenv) أو JSON أو صدفة POSIX أو PowerShell أو صيغة `--env-file` في Docker. التصدير ثم الاستيراد من جديد يعطي ملفًا مكافئًا. ويكتب `env export -o` ملفًا قابلًا للقراءة لك وحدك ولا يستبدل ملفًا موجودًا دون `--force`.
- **النسخ الاحتياطية في Octa Pass:** البيئات جزء من تصدير Octa Pass المشفّر وتُستورد دون فقدان متغيراتها وترتيبها وعلامات إخفائها وملاحظاتها ومشروعها ومرحلتها. أما تصدير CSV فلا أعمدة فيه لها، فتوضع متغيراتها في عمود الملاحظات، كما تُوضع البطاقات وشبكات Wi-Fi.

:::caution[الملفات غير مشفّرة]
`env export -o` و`--env-file-out` و`inject -o` تكتب نصًا صريحًا. هي خاصة بمستخدمك، لكن أي شيء يستطيع قراءة ملفاتك ما دام الملف موجودًا يستطيع قراءة الأسرار. احذف الملفات المصدَّرة عندما تنتهي، وفضّل `run` أو الخطّاف حين تستطيع الأداة قبول متغيرات البيئة.
:::