متن فارسی که در مسیر SSH به علامت سؤال تبدیل شد: ماجرای رکوردهای خراب

ماجرا و علامت‌ها

کار ساده به نظر می‌رسید: یک متن فارسی باید روی سرور اصلاح می‌شد. از سیستم ویندوزی خودمان با ابزار SSH وارد شدیم و فرمان را همراه با متن فارسی فرستادیم. اول متن را داخل آرگومان فرمان گذاشتیم و بعد به شکل heredoc هم امتحان کردیم.

در هر دو حالت نتیجه یکی بود. روی سرور هر حرف فارسی به «؟» تبدیل شده بود و هیچ خطایی هم دیده نشد. فرمان موفق تمام شد و مقدار خراب در دیتابیس نوشته شد. چند رکورد با همین متن خراب ذخیره شد و بعداً باید اصلاح می‌شد.

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

ردگیری علت

اولین سوال این بود که مشکل از روش گذاشتن متن در فرمان است یا از خود مسیر انتقال. چون هم آرگومان و هم heredoc همین نتیجه را دادند، مشکل کوتوِیشن (quote) یا روش نوشتن فرمان نبود. همین مشاهده ساده، دایره را به مسیر انتقال محدود کرد.

بعد به سراغ سمت دیگر رفتیم: آیا سرور متن را اشتباه ذخیره می‌کند؟ ولی علامت سؤال در مقدار ذخیره‌شده یک نشانه مهم بود. اگر سرور بایت‌های درست را با کدگذاری اشتباه می‌خواند، معمولاً حروف عجیب و ناخوانا می‌دیدیم (چیزی شبیه به حروف لاتین با نشانه‌های اضافه). یک ردیف علامت سؤال یکدست، نشان می‌دهد اطلاعات حروف پیش از رسیدن به سرور از بین رفته است. این استدلال است، نه اندازه‌گیری روی بایت‌های مسیر؛ ولی با رفتار ابزار ویندوزی که در بخش بعد می‌آید جور درمی‌آید.

در عمل، راهی که قطعی‌اش می‌کند این است که فایلی را که به سرور رسیده یا خروجی دریافتی را به شکل بایتی (hex) نگاه کنید. اگر به‌جای بایت‌های حروف فارسی فقط مقدار ۳f تکرار شده باشد، آسیب قبل از سرور رخ داده است.

علت اصلی: کدپیج کنسول به‌جای UTF-8

ابزار SSH ویندوزی آرگومان‌ها را با کدپیج کنسول می‌فرستاد، نه با UTF-8. کدپیج جدولی است که هر کد بایتی را به یک نویسه نگاشت می‌کند. مستندات مایکروسافت درباره Console Code Pages توضیح می‌دهد که هر کنسول کدپیج ورودی و خروجی جداگانه دارد، و متن UTF-8 فقط وقتی به APIهای خانواده A داده می‌شود که کدپیج روی 65001 (یعنی CP_UTF8) تنظیم شده باشد. همان مستند توصیه می‌کند برنامه‌های جدید از کدپیج‌ها دور بمانند و از Unicode (خانواده W با UTF-16) استفاده کنند.

کدپیج پیش‌فرض یک سیستم ویندوزی معمولاً یک کدپیج قدیمی تک‌بایتی است که حروف فارسی در آن وجود ندارد. وقتی متن یونیکد باید به چنین کدپیجی تبدیل شود، نویسه‌هایی که در آن جدول نیستند معمولاً با «?» جایگزین می‌شوند. این تبدیل در سمت فرستنده و قبل از ارسال انجام می‌شود. از آن لحظه به بعد، در جریان داده فقط بایت ۳f (همان «?» در ASCII) هست و هیچ ردی از حرف اصلی نمانده است.

دلیل اینکه سرور اعتراضی نکرد هم همین است. طبق RFC 3629، در UTF-8 نویسه‌های ASCII با یک بایت نوشته می‌شوند و نویسه‌های بالاتر با دو تا چهار بایت؛ حروف فارسی دو بایتی‌اند. علامت سؤال یک بایت ASCII کاملاً معتبر است، پس سرور هیچ بایت نامعتبری نمی‌دید که رد کند. دیتابیس هم فقط یک رشته معتبر را ذخیره کرد. نکته مهم‌تر: برخلاف خطای تبدیل در سمت دیتابیس (مثلاً مستندات PostgreSQL می‌گوید اگر نویسه‌ای قابل تبدیل بین کدگذاری‌ها نباشد، خطا گزارش می‌شود)، جایگزینی در سمت کلاینت بی‌صدا اتفاق می‌افتد، چون از دید سرور داده سالم است.

خلاصه اینکه زنجیره درست این بود: متن یونیکد روی ویندوز، تبدیل به کدپیج کنسول (با جایگزینی بی‌صدا)، ارسال از طریق SSH، و ذخیره‌شدن یک رشته معتبر ولی بی‌معنی. هر کدام از حلقه‌ها جداگانه «درست کار می‌کرد».

راه‌حل: فایل UTF-8 و انتقال فایل

تصمیمی که گرفتیم ساده است: متن فارسی هرگز از مسیر آرگومان یا heredoc ویندوزی عبور نمی‌کند. هر متن یا SQL فارسی را روی سیستم خودمان در یک فایل UTF-8 می‌سازیم، خود فایل را به سرور منتقل می‌کنیم و روی سرور از روی فایل اجرایش می‌کنیم. چون فایل با بایت منتقل می‌شود، هیچ تبدیل کدپیجی در راه نیست. جستجوی فارسی روی سرور هم همین‌طور است: عبارت جستجو را داخل فایل می‌گذاریم و از روی فایل می‌خوانیم، نه از روی آرگومان.

نمونه عمومی زیر، با مقادیر ساختگی، همین الگو را نشان می‌دهد. دو نکته مهم است: فایل باید UTF-8 باشد (ترجیحاً بدون BOM)، و پیش از اجرا بایت‌های فایل روی سرور بررسی شود.

# روی ویندوز (PowerShell 7): ساخت فایل UTF-8 بدون BOM
Set-Content -Path fix.sql -Value $sql -Encoding utf8NoBOM

# انتقال فایل به‌صورت بایتی
scp fix.sql deploy@example.com:/tmp/fix.sql

# بررسی بایت‌ها روی سرور: حروف فارسی باید با d8 یا d9 شروع شوند
ssh deploy@example.com "head -c 64 /tmp/fix.sql | xxd"

# اجرا از روی فایل (دستور کلاینت دیتابیس را جایگزین کنید)
ssh deploy@example.com "your-db-client -f /tmp/fix.sql"

درس‌ها و چک‌لیست

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

نکته سوم درباره‌ی خود مسئله است: وقتی خطایی نیست، موفقیت فرمان دلیلی بر درستی داده نیست. باید مقدار نوشته‌شده را بعد از عملیات دوباره بخوانیم و با مقدار مورد انتظار مقایسه کنیم. اگر از ابتدا برای خطاهای رایج فارسی در رابط کاربری دقت داشته‌اید (مثلاً در تایپوگرافی فارسی و RTL)، این همان دقت است ولی این بار در لایه انتقال داده.

در کار با سرورها و زیرساخت، این الگو را بخشی از روال کاری قرار داده‌ایم؛ جزئیات رویکردمان در خدمات سرور و زیرساخت و پروژه زیرساخت سرورها آمده است.