البيئات

قيد التطوير

البيئة هي متغير واحد (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 مثل بقية الأوامر. راجع مرجع واجهة سطر الأوامر للتفاصيل ورموز الخروج.

المراجع

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

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 وخطّاف الصدفة افتراضيًا:

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

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

خطّاف الصدفة

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

eval "$(octapass env hook zsh)"

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

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

Docker

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

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

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

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

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

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

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:

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

# 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 في الخطوات التي تحتاج إلى أسرار:

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:

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

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

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

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

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':

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.