# ۸۴ ریپو غیب شدن. راه‌حلش mkdir بود.

> توی S3 دایرکتوری خالی وجود نداره، و توی یه ریپوی git که کامل پک شده، دایرکتوری‌های refs دقیقاً همین‌ان: خالی. یه سینک فایل‌به‌فایل همه‌ی آبجکت‌ها رو سالم منتقل کرد و اون دو تا دایرکتوری‌ای رو که git لازم داره تا چیزی رو ریپو حساب کنه جا انداخت؛ برای همین ۸۴ تا از ۵۱۷ ریپو غیرقابل‌خوندن برگشتن، در حالی که دیتابیس هنوز می‌گفت کامیت دارن. چک‌های سلامت مهاجرت کل این مدت سبز موندن، چون هیچ‌کدومشون هیچ‌وقت یه ریپو رو باز نمی‌کنن.

- URL: https://ashkmb.com/fa/blog/s3-sync-drops-empty-directories/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-09-18
- Language: fa

سه روز بعد از این‌که یه GitLab خودمیزبان رو مهاجرت دادیم، یکی از همکارها پرسید آیا دو تا پروژه غیب شدن. رابط وب صفحه‌ی پروژه‌ها، فهرست ایشوها و اعضا رو نشون می‌داد. دیتابیس هنوز برای یکی‌شون ۱۲۵ کامیت و ۵۸۴ کیلوبایت ثبت کرده بود. ولی هر چی از git می‌خواستی، جواب می‌داد «A repository for this project does not exist yet».

دو تا پروژه نبود. ۸۴ تا از ۵۱۷ پروژه‌ی کل اینستنس بود، که ۳۴ تاشون فعال بودن، از جمله سرویس‌های پروداکشن. سه روز هیچ‌کس متوجه نشده بود، چون ریپوهای آسیب‌دیده تقریباً طبق تعریف همون‌هایی بودن که اخیراً کسی بهشون دست نزده بود.

## ردی که می‌گه هیچ‌کس چیزی رو پاک نکرده

اولین واکنش غریزی وقتی می‌شنوی «ریپوها غیب شدن» اینه که دنبال یه حذف بگردی. داده‌ها چیز دیگه‌ای می‌گفتن، و مرزبندی اون‌قدر تمیز بود که می‌شد ازش یه قاعده ساخت.

رکورد همه‌ی پروژه‌ها سالم بود: ایشوها، مرج‌ریکوئست‌ها، اعضا، رویدادها، تعداد کامیت درست، اندازه‌ی درست توی دیتابیس. لایه‌ی git زیرش نبود. وقتی متادیتا می‌مونه و داده نه، فرضیه‌ی حذف اشتباهه؛ یه چیزی توی لایه‌ی ذخیره‌سازی اشتباه جابه‌جا شده. اگه متادیتا هم رفته بود، یعنی حذف. متادیتای زنده با داده‌ی گمشده یعنی یه انتقال یا یه مانت، و تو رو به سمت مسیری می‌فرسته که بایت‌ها طی کردن، نه به سمت کارهای یه آدم خاص.

همین مرزبندی نذاشت ساعت اول بررسی صرف این بشه که کی چی کار کرده، و به‌جاش ما رو فرستاد سراغ مهاجرت.

## چیزی که git واقعاً لازم داره

ریپوی git «فایل‌ها» نیست. یه گراف از آبجکت‌هاست، به‌اضافه‌ی مجموعه‌ای از رفرنس‌ها که به نقطه‌هایی از اون گراف اشاره می‌کنن. رفرنس‌ها زیر `refs/` زندگی می‌کنن: سر برنچ‌ها توی `refs/heads` و تگ‌ها توی `refs/tags`، که به‌طور سنتی برای هر رفرنس یه فایل کوچیکه.

وقتی ریپوها بزرگ می‌شن، فرایند housekeeping این رفرنس‌ها رو توی یه فایل واحد `packed-refs` پک می‌کنه، همون‌طور که آبجکت‌های شُل پک می‌شن. یه بهینه‌سازی معمول برای کاراییه که هیچ‌کدوم از کاربرهای ریپو نمی‌بیننش. ولی وقتی پک کردن تموم شد، `refs/heads` و `refs/tags` هیچ فایلی ندارن. دایرکتوری‌های خالی‌ان.

با این حال git هنوز لازم داره `refs/` وجود داشته باشه تا یه دایرکتوری رو ریپو حساب کنه. پس ریپوهایی که از همه دقیق‌تر نگه‌داری شده بودن، یعنی پک‌شده‌ها، دقیقاً همون‌هایی بودن که دایرکتوری مورد نیاز git توشون خالی بود.

## توی S3 دایرکتوری خالی وجود نداره

توی مهاجرت، درخت ذخیره‌سازی Gitaly از مسیر S3 رد شده بود و با `aws s3 sync` بازگردانی شده بود. این مسیر به دلیل‌های خوبی انتخاب شده بود: نه تغییری در مسیریابی، نه تغییری در سکیوریتی گروپ‌ها، هیچ چیزی روی مسیر شبکه دست نمی‌خورد، و سینکی که در هر دو جهت افزایشیه، تا الگوی «اول پیش‌بارگذاری، بعد فقط تغییرات» توی یه پنجره‌ی فریز کوتاه جواب بده.

ولی کلیدهای S3 تخت‌ان. توی مدل آبجکت اصلاً دایرکتوری وجود نداره؛ دایرکتوری استنتاجیه که کلاینت از پیشوند کلیدها می‌کنه، و دایرکتوری‌ای که هیچ فایلی زیرش نیست، چیزی نداره که ازش استنتاج بشه. پس به مقصد نمی‌رسه.

هیچ‌کدوم از این‌ها توی شمارش بایت‌ها دیده نمی‌شه. ما اندازه‌ها رو دو طرف مقایسه کرده بودیم و دو طرف با هم جور بودن، چون دایرکتوری خالی هیچ بایتی نداره. همه‌ی آبجکت‌ها سالم منتقل شدن. اون دو تا دایرکتوری خالی که git لازم داره، توی مقصد اصلاً وجود نداشتن، و git حاضر نشد اون درخت رو به‌عنوان ریپو بشناسه، در حالی که تک‌تک آبجکت‌های تک‌تک کامیت‌ها همون‌جا بودن.

این همون بخشیه که ارزش داره ملکه‌ی ذهنت بشه. کپی وفادار بود. دقیقاً همون چیزی رو منتقل کرد که قراردادش می‌گه: آبجکت‌ها. قرارداد، فایل‌سیستم نیست، و معنا رو فایل‌سیستم حمل می‌کرد.

## حسابی که یه حدس رو به علت ریشه‌ای تبدیل کرد

تا مدتی انتخاب‌ها تصادفی به نظر می‌رسید، و این همون شکلیه که آدم رو به فرضیه‌اش بدبین می‌کنه. چرا این ۸۴ تا؟ بعضی‌هاشون سال‌ها بی‌استفاده بودن، ولی روی یکی‌شون شش هفته پیش پوش شده بود. نظریه‌ی غلط از داخل همین شکلیه: تصادفی.

بعد شمردیم. ۵۱۷ ریپوی دارای محتوا. ۴۳۳ تاشون فایل‌های رفرنس شُل داشتن، پس دایرکتوری‌های `refs/` اون‌ها فایل داشت و برای همین از سینک جون سالم به در برد. ۸۴ تا نداشتن. ۵۱۷ مساوی ۴۳۳ به‌اضافه‌ی ۸۴، بدون هیچ باقی‌مونده‌ای.

آسیب کاملاً به این بستگی داشت که housekeeping ریپو رو پک کرده بود یا نه. برای همینه که بیشتر ریپوهای قدیمی و بی‌استفاده رو گرفت و با این حال یه ریپوی تازه رو هم گرفت: پک شدن تابع تاریخچه‌ست، نه فعالیت فعلی. همبستگی‌ای که از شمارش دقیق جون سالم به در ببره علت ریشه‌ایه؛ باقی‌مونده‌ی صفر اثباتشه.

## چک‌هایی که سبز موندن

بخش ناخوشایندش این‌جاست. معیارهای خروج مهاجرت امضا شده بودن و چک‌هایی که توشون اسم برده شده بود پاس شده بودن. همه‌ی سیگنال‌های سلامت هر سه روز سبز بودن.

| چک | واقعاً چی کار می‌کنه |
|---|---|
| `gitlab:gitaly:check` | یه خط: سرویس رو پروب می‌کنه، هیچ‌وقت یه ریپو رو باز نمی‌کنه |
| `gitlab:check` | حدود ۵۶۰ خط درباره‌ی کانفیگ، اتصال و نیم‌اسپیس‌ها |

اونی که گمراهت می‌کنه، `gitlab:check` هست. برای هر پروژه یه خط چاپ می‌کنه، که کاملاً شبیه یه چک به ازای هر ریپوئه. زیر عنوان «Projects have namespace» دسته‌بندی شده. هیچ‌وقت به یه ریپو دست نمی‌زنه. هر دو چک در حالی تمیز برگشتن که ۱۶ درصد ریپوهای اینستنس غیرقابل‌خوندن بودن، و فردا هم با همین خرابی دوباره تمیز برمی‌گردن.

تسک‌هایی که واقعاً چک می‌کنن این دو تان: `git:fsck`، که یکپارچگی همه‌ی ریپوها رو راستی‌آزمایی می‌کنه، و `git:checksum_projects`، که از رفرنس‌های هر پروژه چک‌سام می‌گیره. هیچ‌کدوم جزو `gitlab:check` نیستن، و دقیقاً برای همین هیچ‌کدوم اجرا نشدن. معیارهای خروج اسم دو تا تسکی رو آورده بودن که به‌طور اثبات‌پذیر نمی‌تونستن همون خرابی‌ای رو که قرار بود جلوش رو بگیرن تشخیص بدن.

تسک `checksum_projects` ابزار درست برای دور و بر هر مهاجرتیه، و برای گرفتن خرابی لازم نیست بدونه چی خراب شده: قبل از انتقال روی مبدأ اجراش کن، بعدش روی مقصد، و دیف بگیر. اگه یه `refs/` جا افتاده باشه، فوراً معلوم می‌شه. راستی‌آزمایی فقط چیزی رو ثابت می‌کنه که واقعاً تستش می‌کنه، و ارزون‌ترین زمان برای فهمیدن این‌که یه چک چی رو تست می‌کنه، قبل از اینه که بهش تکیه کنی.

## این الگو کجاها تکرار می‌شه، و نقطه‌ی کور

بازیابی، چهار تا فراخوانی `mkdir` برای هر ریپو بود. نه ریستوری، نه ری‌استارتی، و هیچ‌جا هیچ داده‌ای از دست نرفت. همون لحظه‌ای که دایرکتوری‌ها ساخته شدن، ریپوها برگشتن.

قاعده‌ها، به ترتیب این‌که چقدر برامون گرون تموم شدن:

دایرکتوری خالی هم داده‌ست. هر درختی که ساختارش معنا داره، مثل ریشه‌ی ذخیره‌سازی git، یه اسپول ایمیل، یا دایرکتوری یه اپلیکیشن که یه دایرکتوری قفل داره، باید با ابزاری منتقل بشه که قراردادش فایل‌سیستم رو هم شامل می‌شه. به‌جای سینک فایل‌به‌فایل، درخت رو با `tar` بسته‌بندی کن و بفرست توی S3، و کل مشکل ناپدید می‌شه؛ چون tar دایرکتوری‌ها رو به‌عنوان ورودی‌های خودش حمل می‌کنه، نه این‌که از کلیدها استنتاجشون کنه.

چک سبز فقط درباره‌ی سؤالی که همون چک می‌پرسه مدرکه. معیارهای خروج یه مهاجرت فهرستی از سؤال‌هاست، و اگه هیچ‌کس بررسی نکرده باشه که چک‌ها واقعاً چی رو تست می‌کنن، ممکنه اون فهرست، فهرست سؤال‌های اشتباه باشه.

و قاعده‌ی صادقانه. چند ماه قبل از انتقال، مسیر سینک بررسی شده بود و فهرستی از چیزهایی که بی‌صدا جا می‌اندازه نوشته شده بود: هارد لینک‌ها، سیم‌لینک‌ها، مالکیت فایل‌ها. هر مورد همون موقع با دقت اندازه‌گیری شده بود. دایرکتوری‌های خالی توی فهرست نبودن. اون یادداشت اوایل همون مهاجرتی نوشته شد که بعداً از دقیقاً همین مسیر استفاده کرد، و تنها موردی که از یه فهرست در بقیه‌ی موارد دقیق جا افتاده بود، همونی بود که ۸۴ ریپو رو خراب کرد.

فهرست چیزهایی که یه ابزار جا می‌اندازه فقط به اندازه‌ی نقطه‌های کورش خوبه، و لبه‌ها از داخل دیده نمی‌شن، قبل و بعد دقیقاً به یه شکل. چکی که می‌تونست این رو بگیره یه دستوره، و جاش قبل از هر انتقال به آبجکت استوریجه: `find <tree> -type d -empty | wc -l`. اگه این عدد صفر باشه، سینک می‌تونه درخت رو منتقل کنه. اگه نباشه، این عدد فهرست چیزهاییه که دارن گم می‌شن، نوشته‌شده قبل از این‌که برن، نه بعدش.
