پیکربندی

فایل پیکربندی کل ربات را توصیف می‌کند: اتصال تلگرام، کاربران مجاز، منوی دکمه‌ها و گزارش‌گیری. آن را با --config به فرمان‌های run، validate، fmt و list-functions می‌دهید (CLI را ببینید).

همهٔ کلیدها از lower_snake_case استفاده می‌کنند. کلیدهای ناشناخته رد می‌شوند؛ بنابراین غلط تایپی خطایی است که هنگام اعتبارسنجی فوراً می‌بینید.

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

تازه شروع کرده‌اید؟ از اجرا در CLI آغاز کنید که ساخت نخستین پیکربندی را گام‌به‌گام توضیح می‌دهد. برای واژگان زیر، مفاهیم را ببینید.

پیکربندی کمینه

فقط telegram (با توکن و یک کاربر مجاز) و menu الزامی‌اند. بقیه مقدار پیش‌فرض دارند:

شروع با یک کاربر مجاز و سه دکمهٔ وضعیت

config.yaml (کمینه)

telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allowed_users:
    - "123456789"

menu:
  - name: System Status
    type: category
    icon: "🖥️"
    items:
      - name: Uptime
        type: button
        icon: "🕒"
        function: command
        command: "uptime"
      - name: Memory
        type: button
        icon: "🧮"
        function: command
        command: "free -h"
      - name: Disk Space
        type: button
        icon: "💾"
        function: command
        command: "df -h /"

پوشهٔ config-examples/ در نسخه، نمونهٔ کمینه و کامل را در خود دارد.

فیلدهای ریشه

فیلد	نوع	الزامی	پیش‌فرض	توضیح
telegram	object	بله	—	تنظیمات تلگرام (پایین را ببینید)
menu	list	بله	—	درخت منو؛ دست‌کم یک گره
function_directory	string	خیر	تنظیم‌نشده	دایرکتوری YAML توابع سفارشی (قواعد پایین)
shell	string	خیر	/bin/bash	Shell به‌شکل shell -c "<command>"
timeout	duration	خیر	60s	timeout پیش‌فرض فرمان
max_output_bytes	int	خیر	524288	بیشترین خروجی نگه‌داری‌شده برای هر فرمان (مقدار خروجی فرمان و کنترل خروجی)
output	auto | text | file	خیر	auto	نحوهٔ تحویل نتیجهٔ فرمان (مقدار خروجی فرمان و کنترل خروجی)
max_output_messages	int	خیر	2	فقط در ریشه. در حالت auto، اگر نتیجه به بیش از این تعداد پیام نیاز داشته باشد یک فایل .txt فرستاده می‌شود (۱ تا ۱۰). ننویسید تا همان ۲ بماند. کنترل خروجی را ببینید
workdir	string	خیر	cwd فرایند	دایرکتوری کاری پیش‌فرض فرمان‌ها
env	map	خیر	خالی	متغیرهای محیطی بیشتر برای فرمان‌ها
menu_columns	int	خیر	2	تعداد دکمه‌های گزینه در هر ردیف زیر کادر پیام
page_size	int	خیر	8	تعداد گزینه‌های هر صفحه پیش از صفحه‌بندی
confirm_ttl	duration	خیر	5m	مدت اعتبار پیام تأیید
delivery_retry_backoff	duration	خیر	1s	فقط ریشه. مدت انتظار اولیه پیش از نخستین تلاش دوباره پس از شکست ارسال. ببینید تلاش مجدد برای ارسال
delivery_retry_backoff_max	duration	خیر	30s	فقط ریشه. بیشترین مدت انتظار میان تلاش‌ها. ببینید تلاش مجدد برای ارسال
delivery_retry_ttl	duration	خیر	2m	فقط ریشه. کل مدتی که ربات پیش از کنارگذاشتن تلاش می‌کند (فقط در گزارش سرور ثبت می‌شود). ببینید تلاش مجدد برای ارسال
enable_run_command	bool	خیر	false	نمایش دکمهٔ $ >_ Run Command که پیام بعدی را به‌عنوان فرمان شِل اجرا می‌کند. پیش‌فرض خاموش است. هر کاربر ربات می‌تواند هر فرمانی روی میزبان اجرا کند؛ فقط اگر به همهٔ کاربران مجاز اعتماد دارید آن را روشن کنید. قرار دادن این کلید زیر telegram نامعتبر است.
logging	object	خیر	گزارش‌گیر پیش‌فرض توکار	گزارش‌گیرهای نام‌دار (پایین را ببینید)

اگر shell را حذف کنم چه می‌شود؟

می‌توانید آن را حذف کنید؛ ربات از /bin/bash استفاده می‌کند. برای timeout، page_size و دیگر فیلدهای اختیاری ریشه نیز پیش‌فرض‌ها اعمال می‌شوند. فقط برای مقدار غیراستاندارد آن‌ها را تنظیم کنید، مانند shell: /bin/sh.

مقدار خروجی فرمان که می‌بینید

دو محدودیت به‌ترتیب اعمال می‌شوند. max_output_bytes محدودیت شما است و روی محدودیت تلگرام که عوض‌کردنی نیست می‌نشیند.

۱. محدودیت شما: max_output_bytes (پیش‌فرض 524288، یعنی ۵۱۲ کیلوبایت)

هنگام اجرای فرمان، ربات حداکثر این مقدار از خروجی عادی و خطا را جداگانه نگه می‌دارد. بیشتر از آن دور ریخته می‌شود، ولی خود فرمان تا پایان یا رسیدن به timeout ادامه می‌یابد. در این حالت نتیجه با (output truncated) شروع می‌شود.

۲. نحوهٔ تحویل نتیجه: output (پیش‌فرض auto)

تلگرام حداکثر ۴۰۹۶ بایت در هر پیام جای می‌دهد. ربات می‌تواند نتیجهٔ بلند را به چند پیام ریپلای بشکند یا کل خروجی را به‌صورت فایل .txt بفرستد. حالت را با output در ریشهٔ پیکربندی انتخاب کنید یا روی یک دکمه عوض کنید:

مقدار	رفتار
auto	تا وقتی نتیجه در max_output_messages پیام جا شود (پیش‌فرض ۲) متن می‌فرستد؛ اگر بیشتر لازم باشد یک فایل .txt می‌فرستد.
text	همیشه به پیام متنی می‌شکند. همچنان بعد از ۱۰ پیام می‌ایستد و بریده‌شدن را اعلام می‌کند.
file	همیشه یک فایل .txt با کپشن کوتاه (نام دکمه، کد خروج، مدت) می‌فرستد.

در حالت‌های auto و file فایل شامل سربرگ و stdout و stderr است؛ پس بالا بردن max_output_bytes واقعاً خروجی بیشتری به شما می‌رساند. اگر ارسال فایل شکست بخورد، ربات ابتدا خودکار دوباره تلاش می‌کند و تنها پس از کنارگذاشتن تلاش به مسیر پیام متنی برمی‌گردد. ببینید تلاش مجدد برای ارسال.

لازم نیست output یا max_output_messages را بنویسید. اگر ننویسید، ربات auto و ۲ را به کار می‌برد. کانفیگی که الان کار می‌کند همان‌طور می‌ماند. max_output_messages فقط در ریشه است. روی دکمه output را نگذارید تا مقدار ریشه استفاده شود؛ فقط وقتی بنویسید که همان دکمه همیشه فایل یا همیشه متن باشد.

برای لاگ‌های بلند، output: auto (پیش‌فرض) یا output: file روی همان دکمه را ترجیح دهید. اگر فقط انتهای لاگ لازم است، خود فرمان را هم می‌توانید کوتاه کنید.

بیشتر بخوانید: کنترل خروجی

یک صفحهٔ کامل به همین سه فیلد اختصاص دارد. آن صفحه همهٔ ترکیب‌های ریشه و دکمه را یکی‌یکی شرح می‌دهد و برای هرکدام تصویری از گفتگوی تلگرام نشان می‌دهد.

خواندن کنترل خروجی

قواعد function_directory

وضعیت	نتیجه
کلید وجود ندارد	گزارش info؛ فقط توابع توکار
کلید وجود دارد اما خالی است ("")	گزارش info؛ فقط توابع توکار
کلید به مسیر ناموجود یا غیرقابل دسترسی اشاره می‌کند	خطای قطعی؛ فرایند متوقف می‌شود
مسیر وجود دارد اما دایرکتوری خالی است	مجاز

مسیر نادرست ربات را متوقف می‌کند

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

telegram

فیلد	نوع	الزامی	پیش‌فرض	توضیح
bot_token	string	بله	—	توکن ربات از BotFather
allowed_users	list of string	بله	—	کاربران مجاز
api	string	خیر	https://api.telegram.org	URL پایهٔ Bot API
proxy.enabled	bool	خیر	false	استفاده از پراکسی برای Telegram API
proxy.url	string	مشروط	—	هنگام true بودن proxy.enabled الزامی
insecure	bool	خیر	false	نادیده گرفتن بررسی TLS (توصیه نمی‌شود)

کاربران غیرمجاز پیامی شامل user_id و username دریافت می‌کنند تا از مدیر دسترسی بخواهند. بار نخست شناسهٔ خودتان را نیز همین‌گونه پیدا می‌کنید؛ اجرا در CLI ← گام ۵ را ببینید.

اتصال از طریق پراکسی

بخش telegram با پراکسی

telegram:
  bot_token: "123456789:AAExampleTokenValue"
  allowed_users:
    - "123456789"  # numeric user ID
    - "@alice"  # or username
  proxy:
    enabled: true
    url: "socks5://127.0.0.1:10808"

برای اینکه کاربران مجاز بتوانند فرمان شِل را در تلگرام بنویسند، این تنظیم را در ریشهٔ فایل بگذارید (نه زیر telegram):

افزودن یک تنظیم ریشه

فعال کردن دکمهٔ Run Command

enable_run_command: true

منو

این بخش مرجع فیلدهاست. برای توضیح هدایت‌شده همراه نمونه، منو را ببینید. هر گره دکمه یا دسته:

فیلد	نوع	الزامی	توضیح
name	string	بله	نام نمایشی (میان هم‌سطح‌ها بدون توجه به بزرگی حروف یکتا)
type	category | button	بله	نوع گره
items	list	برای category بله	فرزندان؛ دسته باید دست‌کم یکی داشته باشد
function	string	برای button بله	نام تابع
command	string	برای function: command بله	فرمان شِل برای command توکار
path	string	برای function: script بله	مسیر اسکریپت برای script توکار
icon	string	خیر	پیشوند ایموجی اختیاری
id	string	خیر	شناسهٔ اختیاری این گره؛ می‌توانید حذفش کنید
confirm	bool	خیر	درخواست تأیید پیش از اجرا (پیش‌فرض false)
timeout	duration	خیر	بازنویسی timeout سراسری
workdir	string	خیر	بازنویسی دایرکتوری کاری
env	map	خیر	متغیر محیطی بیشتر برای این دکمه
columns	int	خیر	بازنویسی ستون‌های این دسته
output	auto | text | file	خیر	اختیاری. ننویسید تا output ریشه استفاده شود. فقط وقتی بگذارید که این دکمه حتماً file یا text باشد (مقدار خروجی فرمان و کنترل خروجی)
args	string	خیر	آرگومان‌های اختیاری script
هر نام پارامتر تعریف‌شده	scalar	طبق تعریف تابع	مقدار داده‌شده به تابع، مانند url، host، unit یا lines

روی دکمه، هر کلید scalar دیگر پارامتر تابع است. نام آن باید با پارامتری از تابع انتخاب‌شده مطابقت داشته باشد. نام ناشناخته validate را ناموفق می‌کند. مقادیر int یا bool نیز بررسی می‌شوند. رشته، عدد و بولی مستقیم به‌شکل مقدار YAML نوشته می‌شوند و عدد به نقل‌قول نیاز ندارد.

روی دسته، هر کلید خارج از فیلدهای دستهٔ بالا خطاست. دسته تابع اجرا نمی‌کند، پس کلید پارامتر نمی‌پذیرد.

command، path و args میانبر پارامترهایی با همان نام‌اند. نام دیگر پارامترها مستقیم روی دکمه نوشته می‌شود. مقادیر را در نگاشت تودرتوی params: نگذارید. توابع ← فرستادن مقادیر از دکمه را ببینید.

logging

اختیاری است. اگر حذف شود، گزارش‌گیر پیش‌فرض کنسول روی stderr با سطح info استفاده می‌شود.

گزارش‌گیرهای نام‌دار:

نوشتن گزارش عادی و فایل حسابرسی

بخش logging با فایل حسابرسی

logging:
  logs:
    default:
      level: info
      format: console  # or JSON
      output:
        - output: stderr
    audit:
      level: info
      format: json
      output:
        - output: file
          file: /var/log/telegram-commander/audit.log

خروجی‌های پشتیبانی‌شده: stdout، stderr، file و discard.

گزارش‌گیر audit بالا هر فرمان را ثبت می‌کند: اجراکننده، دکمه، کد خروج و مدت اجرا. گزارش حسابرسی را ببینید.

صفحات مرتبط

• اجرا در CLI — ساخت و اجرای نخستین پیکربندی
• منو — شرح کامل درخت منو
• تلاش مجدد برای ارسال — تلاش خودکار دوباره پس از قطعی کوتاه شبکه
• کنترل خروجی — پیام در برابر فایل .txt، با همهٔ ترکیب‌های ریشه و دکمه
• توابع — معنی function، command، path و args
• CLI — اعتبارسنجی و اجرا با پیکربندی