اجرای dsh بهصورت headless روی VPS با systemd
آموزش اجرای dsh بهعنوان سرویس systemd روی VPS، با کاربر اختصاصی، نسخه ثابت، Restart، لاگهای journalctl و تونل SSH برای دسترسی به رابط کاربری.
اجرای dsh بهصورت headless روی VPS، نه در ترمینال
اجرای dsh بهصورت headless روی VPS به یک فایل unit در systemd و یک کاربر اختصاصی برای مالکیت آن نیاز دارد. dsh، راهانداز خط فرمان DeepSeek Harness، یعنی runtime عامل DeepSeek است که در August 2026 و در قالب developer preview، تحت مجوز MIT منتشر شده است. harness برنامهای پیرامون مدل است، نه خود مدل؛ بنابراین چیزی که زیر systemd اجرا میکنید حلقه، ابزارها و مجوزها است، نه inference مربوط به DeepSeek. راهنمای quickstart از شما میخواهد npx @deepseek-ai/dsh web را وارد کنید؛ این کار درست است، اما اجرای آن بلافاصله پس از بستن نشست SSH (secure shell) شما متوقف میشود.
یک فایل unit چهار مورد را همزمان حل میکند. سرویس پس از reboot دوباره اجرا میشود. خروجی آن به journal میرود و از مقابل شما عبور نمیکند. سرویس با حسابی اجرا میشود که root نیست. همچنین نسخهای که اجرا میشود همان نسخهای است که انتخاب کردهاید. این موضوع در اینجا بیش از حد معمول اهمیت دارد، زیرا upstream با حروف بزرگ اعلام کرده است:
DeepSeek Harness در حال حاضر در وضعیت developer preview قرار دارد و با سرعت زیادی تغییر میکند. تغییرات ناسازگارکننده در سازگاری رخ خواهد داد.
این راهنما فرض میکند dsh را قبلاً بهصورت دستی اجرا کردهاید و برای شما کار میکند. اگر چنین نیست، با نصب DeepSeek Harness روی VPS شروع کنید و پس از آن برگردید که npx @deepseek-ai/dsh web یک صفحه ارائه دهد.
ابتدا Node، زیرا هشدارهای npm کافی نیستند
node -vبسته پیشفرض در Ubuntu 24.04 نسخه Node 18 (نسخه 18.19.1 تا اوت 2026) است که برای بستهای که در سال جاری منتشر شده، قدیمی محسوب میشود. خود npm نسخههای Node را بررسی میکند: مستندات آن میگوید فیلد engines در یک بسته، «فقط هشدار تولید میکند» مگر اینکه engine-strict را فعال کنید. مانیفستهای منتشر شده @deepseek-ai/dsh اصلاً فیلد engines ندارند (بررسیشده در 27 اکتبر 2026 برای 0.1.0-rc.7، 0.2.1-rc.2 و 0.2.1-rc.4)، با اینکه مخزن آن را اعلام کرده است، اما npm نیازمندیهای موتور وابستگیها را نیز چک میکند. نسخه پینشده 0.2.1-rc.2 مقدار commander: ^15.0.0 را اعلام میکند و Commander 15 به Node >=22.12.0 نیاز دارد، بنابراین نصب آن روی Node 18 اوبونتو، تحت تنظیمات عادی npm یک هشدار EBADENGINE ایجاد میکند. این هشدار بهطور پیشفرض نصب را متوقف نمیکند، پس پیش از رسیدن به خطای زمان اجرا (runtime failure)، Node را بررسی کنید.
حداقل نسخه مورد نیاز مخزن نیز تغییر کرده است. منبع 0.2.1-rc.2 نسخه ^22.19.0 || >=24.0.0 را میپذیرد، اما بسته CLI در شاخه master اکنون >=24.9.0 را اعلام میکند که Node 22 آن را برآورده نمیکند. Node 24 را از NodeSource نصب کنید. این یک نسخه پشتیبانی بلندمدت (LTS) است که از 20 اکتبر 2026 در وضعیت نگهداری قرار گرفته و بیلدهای فعلی آن هر دو محدوده را پوشش میدهند. طبق برنامه انتشار Node.js، Node 26 در تاریخ 28 اکتبر 2026 به وضعیت LTS رسیده است.
curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/nodesource_setup.sh
less /tmp/nodesource_setup.sh
sudo -E bash /tmp/nodesource_setup.sh
sudo apt install -y nodejs
node -vاکنون node -v باید نسخه v24، یعنی 24.9.0 یا جدیدتر را چاپ کند. خط less به این دلیل وجود دارد که پایپ کردن مستقیم یک اسکریپت از راه دور به bash، کدی را اجرا میکند که شما هرگز آن را نخواندهاید.
پیش از نوشتن unit، اجرای آن را اثبات کنید
npx @deepseek-ai/dsh@0.2.1-rc.2 webآن را در حال اجرا رها کنید. از یک نشست SSH دوم:
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/هر کد وضعیت HTTP به این معنی است که پروفایل وب روی loopback در حال گوش دادن است، که محل پیشفرض bind شدن آن است. انتظار یک 401 را داشته باشید و آن را به عنوان موفقیت در نظر بگیرید: رابط کاربری، مرورگرها را با یک launch token در URL چاپشده احراز هویت میکند که آن را با یک session cookie امضاشده معاوضه میکند، و درخواستی که هیچکدام را نداشته باشد، کد 401 دریافت میکند. 000 به همراه curl: (7) Failed to connect to 127.0.0.1 port 3080 به این معنی است که سرویس در حال گوش دادن نیست و ترمینال اول دلیل آن را به شما میگوید. پیش از ادامه، اجرای دستی را با Ctrl+C متوقف کنید: unitای که سعی کند پورتی را bind کند که سرویس دیگری قبلاً اشغال کرده است، با خطای Error: listen EADDRINUSE: address already in use 127.0.0.1:3080 شکست میخورد.
0.1.0-rc.7 نسخه منتشرشده در 18 August 2026 بود و پیش از احراز هویت مرورگر که این راهنما بر آن تکیه دارد، ارائه شده است: فایل Connection README آن میگوید که این حصار یک سیاست دسترسیپذیری است و "حامل وب هیچ لایه احراز هویتی ارائه نمیدهد". در 11 October 2026 تگ latest به 0.2.0-rc.2 اشاره میکرد. در 27 October 2026 تگ latest به 0.2.1-rc.2 و next به 0.2.1-rc.4 اشاره داشت، بنابراین دستورات اینجا نسخه 0.2.1-rc.2 را ثابت (pin) میکنند. در 4 November 2026، لیست نسخههای npm هر دو نسخه latest و next را در 0.2.1-rc.5 نشان میدهد؛ دستورات اینجا همان نسخه ثابتشده فعلی را حفظ میکنند. با استفاده از npm view @deepseek-ai/dsh version بررسی کنید چه نسخهای فعلی است، سپس هر نسخهای که تصمیم به اجرای آن دارید را ثابت کنید.
نصب نسخه پینشده بهصورت سراسری
npx ابزار مناسبی برای استفاده در داخل یک unit file نیست. بدون تعیین نسخه یا وجود یک نصب محلی منطبق، این دستور هنگام شروع پردازش، نسخه بسته را resolve میکند؛ بنابراین، راهاندازی مجدد سرویس پس از سه ماه ممکن است منجر به اجرای بیلد متفاوتی از یک agent در مرحله پیشنمایش شود، بدون آنکه تغییری در تنظیمات شما ایجاد شده باشد. نبود بستهها یا دادههای کش نیز مستلزم دسترسی به npm registry است؛ در نتیجه، کندی registry میتواند باعث تأخیر یا شکست در شروع سرویس شود. npm از اجرای آفلاین و کششده نیز پشتیبانی میکند. نصب را تنها یکبار و با نسخهای که یادداشت کردهاید انجام دهید:
sudo npm install -g @deepseek-ai/dsh@0.2.1-rc.2
command -v dsh
npm ls -g --depth=0 @deepseek-ai/dshcommand -v dsh در صورتی که npm از NodeSource آمده باشد، /usr/bin/dsh و اگر از بستههای خود Ubuntu باشد، /usr/local/bin/dsh را چاپ میکند. از مسیری که در خروجی چاپ شده است در unit file استفاده کنید. npm ls -g نسخه دقیق را چاپ میکند که همان پاسخی است که شش هفته بعد، زمانی که رفتار برنامه تغییر کرده و نصب اولیه را به خاطر نمیآورید، به آن نیاز خواهید داشت. اگر نصب با خطا مواجه شد، یا command -v dsh پس از آن خروجی نداشت، یا نسخهای که دریافت کردید با نسخه درخواستی شما متفاوت بود، پیش از نوشتن unit file، مراحل خطایابی معمول نصب و نسخه dsh را دنبال کنید.
کاربری که مالک سرویس است و هیچ دسترسی دیگری ندارد
این agent دستورات shell را اجرا میکند. این وظیفهٔ اصلی آن است. اجرای آن با دسترسی root باعث میشود هر فراخوانی ابزار، به یک فراخوانی با دسترسی root تبدیل شود؛ بنابراین یک حساب کاربری اختصاصی بدون login shell برای آن ایجاد کنید.
sudo useradd --system --create-home --home-dir /var/lib/dsh --shell /usr/sbin/nologin dsh
sudo install -d -o dsh -g dsh -m 750 /var/lib/dsh/harness /var/lib/dsh/workspace
id dsh/var/lib/dsh/harness به DSH_HOME تبدیل میشود، دایرکتوری که dsh پروفایلها را در آن نگهداری میکند. یک پروفایل، مجموعهای نامگذاریشده از بستههای افزونه (plugin bundles) است که لایهٔ patch اختصاصی شما روی آن قرار دارد، و پروفایلهای web و headless در اولین باری که آنها را بوت میکنید، خود را از روی قالبهای پیشفرض (shipped templates) میسازند. هر چیزی که بعداً به این مجموعه اضافه کنید، با دسترسیهای فایل و shell همان کاربر اجرا میشود، بنابراین بررسی امنیتی افزونه پیش از نصب بخشی از همان وظیفهٔ ایجاد حساب کاربری است. آن بوت اولیه فایلهایی را مینویسد و ممکن است بستههایی را دریافت کند، پس این کار را بهصورت دستی انجام دهید تا بتوانید روند آن را مشاهده کنید.
sudo -u dsh env HOME=/var/lib/dsh DSH_HOME=/var/lib/dsh/harness /usr/bin/dsh --profile webمقدار HOME را بهجای اعتماد به عملکرد پیشفرض sudo، بهصورت صریح تنظیم کنید؛ زیرا اینکه sudo مقدار HOME را حفظ میکند یا بازنویسی، به تنظیماتی از جمله env_reset، env_keep و always_set_home در فایل /etc/sudoers بستگی دارد. اگر این تنظیمات اشتباه باشد، اجرای اولیه سعی میکند از دایرکتوری home شما برای کشها و وضعیت (state) استفاده کند که منجر به خطاهای مجوز (permission errors) میشود یا وضعیت را در جایی قرار میدهد که سرویس بعداً از آن استفاده نخواهد کرد. بهمحض اینکه بررسی curl یک کد وضعیت چاپ کرد، با استفاده از Ctrl+C آن را متوقف کنید.
فایل unit
عبارت /etc/systemd/system/dsh.service را بنویسید:
[Unit]
Description=DeepSeek Harness (dsh) web profile
Documentation=https://github.com/deepseek-ai/deepseek-harness
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=exec
User=dsh
Group=dsh
WorkingDirectory=/var/lib/dsh/workspace
Environment=HOME=/var/lib/dsh
Environment=DSH_HOME=/var/lib/dsh/harness
ExecStart=/usr/bin/dsh --profile web
Restart=on-failure
RestartSec=5s
TimeoutStopSec=30s
SyslogIdentifier=dsh
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
[Install]
WantedBy=multi-user.targetExecStart= مسیر مطلق بهدستآمده از command -v dsh را میپذیرد. systemd برای یک نام دستور ساده، لیستی از مسیرهای ثابت را جستجو میکند، اما این لیست همان PATH پوستهٔ شما نیست؛ بنابراین استفاده از مسیر مطلق، ابهام را از بین میبرد.
WorkingDirectory= جایی است که مسیرهای نسبی در آن حل میشوند و نقطهای است که فراخوانی ابزاری که ls را بدون آرگومان اجرا میکند، از آنجا آغاز میشود. آن را به فضای کاری (workspace) که به agent میدهید، اشاره دهید. اگر دایرکتوری موجود نباشد یا کاربر سرویس نتواند وارد آن شود، unit پیش از اجرای dsh با خطای status=200/CHDIR شکست میخورد.
ProtectHome=true مسیرهای /home و /root را از دید پردازش پنهان میکند. این کار در اینجا ایمن است، زیرا هر چیزی که سرویس با آن سروکار دارد، در زیرشاخه /var/lib/dsh قرار دارد. اگر فضای کاری را به مسیری در زیرشاخه /home اشاره دهید، agent گزارش میدهد که دایرکتوری وجود ندارد؛ این موضوع تا زمانی که این خط را به یاد نیاورید، گیجکننده است. ProtectSystem=full مسیرهای /usr، /boot و /etc را فقطخواندنی (read-only) میکند، چرا که سرویس هرگز نیازی به نوشتن در آنها ندارد.
پیشروی بیشتر وسوسهانگیز است اما معمولاً اشتباه است. ProtectSystem=strict کل سیستم فایل را بهجز شبهسیستمفایلهای هسته و با توجه به PrivateTmp=true، /tmp و /var/tmp در این unit، فقطخواندنی میکند؛ بنابراین عملیات نوشتن در فضای کاری با خطای EROFS: read-only file system مواجه میشود. اگر چنین سطحی از امنیت را میخواهید، ReadWritePaths=/var/lib/dsh را در همان ویرایش اضافه کنید.
کدام Type= باید در اینجا قرار بگیرد؟
Type=exec، زیرا dsh در foreground باقی میماند و هرگز fork نمیکند. مزیت آن نسبت به حالت پیشفرض، دریافت یک پیام خطای واقعی است. با Type=simple، systemd بهمحض آنکه فرایند را fork کند، راهاندازی را موفق تلقی میکند؛ پیش از آنکه بداند فایل binary اصلاً وجود دارد یا نه. در نتیجه، systemctl start dsh بدون خطا برمیگردد و خطا فقط در journal ظاهر میشود. با Type=exec، systemd منتظر میماند تا execve() با موفقیت اجرا شود. بنابراین، اشتباه تایپی در ExecStart= همان فرمانی را که وارد کردهاید با خطا متوقف میکند و خطا را همانجا میبینید.
هر دو پاسخ نادرست باعث توقف میشوند. Type=forking به systemd میگوید منتظر بماند تا یک فرایند parent خارج شود. dsh هرگز خارج نمیشود؛ بنابراین start تا زمان پایان TimeoutStartSec، یعنی بهطور پیشفرض 90 ثانیه، متوقف میماند و سپس Job for dsh.service failed because a timeout was exceeded. را گزارش میکند. Type=notify منتظر یک پیام READY=1 از طریق sd_notify میماند و فرایند Node که هرگز چنین پیامی ارسال نمیکند، به همان شکل باعث توقف میشود. مقایسه کامل انواع سرویس systemd سایر موارد را پوشش میدهد، ازجمله اینکه چه زمانی تنظیم notify ارزش صرف زمان را دارد.
قوانین راهاندازی مجدد که با صدای بلند شکست میخورند
Restart=on-failure در صورت خروج غیر صفر یا دریافت سیگنال نامناسب، سرویس را مجدداً راهاندازی میکند و پس از خروج موفقیتآمیز، unit را به حال خود رها میکند؛ systemd مقادیر SIGHUP، SIGINT، SIGTERM و SIGPIPE را برای این نوع سرویس به عنوان سیگنالهای موفقیتآمیز در نظر میگیرد. این همان رفتاری است که برای یک نسخه پیشنمایش (preview build) انتظار دارید. اگر dsh به دلیل خواندن یک پیکربندی نامعتبر با کد 0 خارج شود، unit متوقف شده و در همان حالت باقی میماند و systemctl status dsh وضعیت inactive (dead) را نشان میدهد که میتوانید آن را مشاهده کنید. Restart=always همین رویداد را به یک حلقه راهاندازی مجدد تبدیل میکند که از دور سالم به نظر میرسد.
محدودیت نرخ (rate limit) بخشی است که معمولاً نادیده گرفته میشود. مقادیر پیشفرض systemd برابر با پنج بار شروع در ده ثانیه است و با RestartSec=5s شما هرگز به پنج بار شروع در بازه ده ثانیهای نمیرسید، بنابراین unitای که هنگام شروع کرش میکند برای همیشه ریاستارت میشود و فقط journal از آن باخبر است. StartLimitIntervalSec=300 به همراه StartLimitBurst=5 اجازه پنج بار شروع در پنج دقیقه را میدهد و پس از آن، از شروع مجدد در آن بازه زمانی خودداری میکند. systemd تسلیم شده و unit را در وضعیت failed قرار میدهد و Start request repeated too quickly. را لاگ میکند. پس از رفع علت مشکل، این وضعیت را با sudo systemctl reset-failed dsh پاک کنید. هر دو تنظیم باید در [Unit] قرار بگیرند، نه [Service]؛ گزینههای ناشناخته به جای نادیده گرفته شدن در سکوت، هشدارهایی در لاگ تولید میکنند.
آن را اجرا و سپس بررسی کنید
sudo systemctl daemon-reload
sudo systemctl enable --now dsh
systemctl status dshenable --now دو وظیفه دارد. enable همان دستوری است که سرویس را پس از reboot دوباره بالا میآورد و --now آن را در boot فعلی اجرا میکند. یک systemctl start ساده پس از reboot بعدی از بین میرود و بهروزرسانیهای kernel نیز به معنای reboot هستند.
systemctl status dsh باید Active: active (running)، یک Main PID و یک خط Memory: را نشان دهد. سپس تأیید کنید که روی چه پورتی در حال گوش دادن است:
sudo ss -lntp | grep 3080شما به 127.0.0.1:3080 نیاز دارید. اگر آدرس دیگری میبینید، یک فلگ --host شنونده (listener) را به شبکهای که آن آدرس به آن تعلق دارد منتقل کرده است و تا زمانی که TLS تنظیم نشده باشد، HTTP ساده ارائه میدهد. نام پردازش در آن خروجی node است، نه dsh، زیرا باینری dsh یک اسکریپت Node است و به همین دلیل pgrep -x dsh چیزی پیدا نمیکند. بهجای آن از systemctl show -p MainPID dsh استفاده کنید.
سپس یک بار سیستم را reboot کنید. سرویسی که هرگز از یک reboot جان سالم به در نبرده است، هنوز یک سرویس کامل محسوب نمیشود.
sudo rebootدوباره متصل شوید و systemctl is-active dsh را اجرا کنید. این دستور active را چاپ میکند.
خواندن لاگها با journalctl
هر چیزی که dsh در stdout و stderr مینویسد، در journal تحت نام unit ثبت میشود.
journalctl -u dsh -f
journalctl -u dsh -n 200 --no-pager
journalctl -u dsh --since "10 min ago" -p errدستور -f خطوط جدید را دنبال میکند، -n تعداد N خط آخر را نمایش میدهد و -p err بر اساس اولویت فیلتر میکند. مقدار SyslogIdentifier=dsh در unit دلیل برچسبگذاری آن خطوط با dsh بهجای node است؛ این موضوع زمانی که برای اولین بار خروجی journal را میخوانید و توسط unit فیلتر نشده است، اهمیت پیدا میکند.
پیش از آنکه به لاگها نیاز پیدا کنید، بررسی کنید که آیا journal پس از reboot باقی میماند یا خیر:
journalctl -u dsh -b -1اگر دستور بالا Specifying boot ID or boot offset has no effect, no persistent journal was found را چاپ کرد، یعنی journal در /run قرار دارد و با هر بار reboot پاک میشود. با استفاده از Storage=auto، دایرکتوری مربوطه را ایجاد کرده و daemon را restart کنید؛ اگر Storage=volatile پیکربندی شده است، ابتدا آن را به persistent تغییر دهید:
sudo mkdir -p /var/log/journal
sudo systemctl restart systemd-journaldدستور sudo journalctl --flush را اجرا کنید تا به ذخیرهسازی دائمی (persistent) سوئیچ کرده و لاگهای boot فعلی را روی دیسک تخلیه کنید.
دسترسی به رابط کاربری از طریق تونل SSH، نه پورت عمومی
dsh بهطور پیشفرض رابط کاربری (UI) خود را روی 127.0.0.1:3080 ارائه میدهد. Loopback پیشفرض است، اما تنها انتخاب نیست: --host یک آدرس IPv4 یا IPv6 مشخص از یک اینترفیس محلی را میپذیرد. هر آدرسی غیر از loopback، شبکه مربوط به خود را از طریق HTTP ساده و با یک هشدار در زمان راهاندازی در دسترس قرار میدهد، مگر اینکه از --tls-cert و --tls-key نیز استفاده کنید. آنچه dsh از آن امتناع میکند، استفاده از wildcard است. اگر --host 0.0.0.0 را درخواست کنید، خطا با این عبارت شروع میشود:
webserver: host "0.0.0.0" is an unspecified (wildcard) address, which is not supported:در ادامه میگوید که «اتصال به همه اینترفیسها، اجرای کد از راه دور (RCE) را در معرض شبکه قرار میدهد» و به شما توصیه میکند که «بهجای آن، یک آدرس IPv4 یا IPv6 مشخص از یک اینترفیس محلی را bind کنید». مقداری که اصلاً یک IP واقعی نباشد، مانند یک hostname، با خطای is not a concrete IPv4 or IPv6 address literal مواجه میشود.
به هر حال، تنظیمات پیشفرض را حفظ کنید. رابط برنامهنویسی (API) وب، عامل (agent) را هدایت میکند و عامل دستورات shell را اجرا میکند. dsh قبل از آن API، احراز هویت قرار میدهد: بررسی Host و Origin، بهعلاوه یک توکن راهاندازی در URL چاپشده که رابط کاربری آن را با یک کوکی نشست (session cookie) امضا شده معاوضه میکند. با این حال، در HTTP ساده، آن توکن بهصورت متن آشکار در شبکه جابهجا میشود و مستندات خودِ upstream میگوید که بررسی Host از خودِ پورت در حال شنود محافظت نمیکند. اگر به رابط کاربری روی یک hostname واقعی نیاز دارید، راهنمای استقرار عمومی DeepSeek یک reverse proxy با --public-url و --trusted-host، یا TLS بومی با --tls-cert و --tls-key را پوشش میدهد. خواندن معنای واقعی آن خط 127.0.0.1:3080 در خروجی راهاندازی پیش از اقدام به تغییر آن، ارزشمند است. برای سیستمی که فقط خودتان از آن استفاده میکنید، پورت را از دستگاه خودتان فوروارد کنید:
ssh -N -L 3080:127.0.0.1:3080 you@203.0.113.10-L 3080:127.0.0.1:3080 پورت 3080 را روی لپتاپ شما باز میکند و هر چیزی که به آنجا برسد را به 127.0.0.1:3080 (آنطور که روی VPS حل میشود) میفرستد. -N به این معنی است که هیچ دستور از راه دوری اجرا نشود، بنابراین نشست فقط تونل را باز نگه میدارد. آن را در حال اجرا بگذارید، URL چاپشده توسط dsh در زمان راهاندازی را با journalctl -u dsh -n 100 --no-pager پیدا کنید و آن را در مرورگر خود باز کنید. آن URL حاوی توکن راهاندازی است. اگر http://127.0.0.1:3080/ خام را در مرورگری که وارد نشده باز کنید، خطای 401 دریافت میکنید. توکن متعلق به فرآیند در حال اجرا است، اما کوکی نشستی که خریداری میکند عمر طولانیتری دارد: کوکی با یک کلید محرمانه که dsh در $DSH_HOME/.credentials.yaml نگه میدارد امضا شده و بهطور پیشفرض 30 روز اعتبار دارد، بنابراین مرورگری که قبلاً وارد شده میتواند حتی پس از راهاندازی مجدد، URL خام را دوباره باز کند. شما فقط برای یک مرورگر جدید، یا زمانی که آن کوکی منقضی شده باشد، به یک URL تازه از journal نیاز دارید. با URL مانند یک اعتبارنامه رفتار کنید: upstream میگوید آن را فقط با کاربران مورد نظر به اشتراک بگذارید و هر کسی که بتواند journal سیستم را بخواند، میتواند آن را بخواند. وقتی وارد شدید، آنجاست که کلید API DeepSeek را در بخش Settings و سپس Models وارد میکنید و دایرکتوری workspace را انتخاب میکنید. workspace را روی /var/lib/dsh/workspace تنظیم کنید، دایرکتوری که متعلق به کاربر سرویس است، در غیر این صورت ابزارهای فایل عامل با EACCES: permission denied شکست میخورند.
اگر پورت 3080 روی لپتاپ شما مشغول باشد، ssh این موضوع را اعلام میکند:
bind [127.0.0.1]:3080: Address already in use
channel_setup_fwd_listener_tcpip: cannot listen to port: 3080یک پورت محلی متفاوت با ssh -N -L 3081:127.0.0.1:3080 you@203.0.113.10 انتخاب کنید، سپس URL چاپشده را با تغییر 3080 به 3081 باز کنید. برای صرفهجویی در تایپ، از ~/.ssh/config روی دستگاه خود استفاده کنید:
Host dsh-vps
HostName 203.0.113.10
User you
LocalForward 3080 127.0.0.1:3080پس از آن، ssh -N dsh-vps کل دستور خواهد بود. این تونل اکنون تنها درِ ورودی به عامل شماست، بنابراین daemon مربوط به SSH همان چیزی است که از آن محافظت میکند: فقط کلیدها، بدون احراز هویت با رمز عبور، و بقیه موارد ایمنسازی SSH روی VPS با قدرت بیشتری نسبت به حالت معمول اعمال میشود. اگر آن VPS به یک شبکه خصوصی کوچک برای خودش تبدیل شد، با یک دیتابیس یا یک سیستم staging در پشت آن، معرفی آن آدرسها به tailnet با یک subnet router شما را از فوروارد کردن به ازای هر سرویس بینیاز میکند، اگرچه با dsh روی حالت پیشفرض loopback، خودِ رابط کاربری همچنان از طریق تونل میرسد.
کلید نباید در فایل unit قرار بگیرد. مقادیر Environment= توسط systemctl show dsh -p Environment چاپ میشوند که هر کاربری روی سیستم میتواند آن را اجرا کند. اگر پلاگینی که نصب میکنید به کلیدی در محیط نیاز دارد، آن را در /etc/dsh.env با دسترسی 600 متعلق به root قرار دهید و با EnvironmentFile=/etc/dsh.env به آن ارجاع دهید. systemd آن فایل را در زمان اجرا به عنوان root میخواند و systemctl show محتویات آن را چاپ نمیکند. اینکه هر تنظیم در نهایت در کدام فایل روی دیسک قرار میگیرد و وقتی dsh را بهجای API DeepSeek به یک endpoint محلی Ollama اشاره میدهید چه چیزی از سیستم شما خارج میشود، موضوع پیکربندی کلیدها، مدلها و endpointهای dsh است.
هزینه اجرای سرویس
Inference در API مربوط به DeepSeek انجام میشود، نه روی VPS شما. سرور شما هزینه اجرای فرایند Node، رابط کاربریای که ارائه میکند و هر فرمانی را که agent تصمیم میگیرد اجرا کند، پرداخت میکند. دو مورد اول پایدار و کمهزینهاند. مورد سوم در این unit file هیچ محدودیتی ندارد.
بهجای اتکا به عددی که از سرور شخص دیگری گرفتهاید، حداقل مصرف را روی سرور خودتان اندازهگیری کنید:
systemctl show dsh -p MemoryCurrent
systemd-cgtop -1 --depth 2MemoryCurrent برحسب bytes است. زمانی که agent در حال کار است آن را monitor کنید، نه زمانی که idle است.
فراخوانیهای ابزار، فرزندهای سرویس هستند. بنابراین در همان control group قرار میگیرند و از همان limitها استفاده میکنند. agentی که npm install یا یک test suite را داخل workspace اجرا میکند، ممکن است با اختلاف زیادی بیشتر از خود harness حافظه مصرف کند. در یک VPS با 1 GB، مشکل معمولاً از همینجا شروع میشود: kernel یک process را انتخاب و آن را kill میکند و journalctl -k | grep -i "out of memory" خط Out of memory: Killed process را نشان میدهد که نام process انتخابشده در آن آمده است. این process اغلب همان processی نیست که مشکل را ایجاد کرده است.
راهحل، تعیین عمدی یک limit است. MemoryMax= و CPUQuota= در بخش [Service]، آسیب را داخل unit نگه میدارند تا یک build خارج از کنترل kill شود، نه اینکه کل سرور قفل کند. محدود کردن حافظه و CPU با systemd اعداد و رفتار هنگام failure را پوشش میدهد. فضای دیسک نیز از history نشستها در DSH_HOME و هر چیزی که agent در workspace مینویسد، افزایش پیدا میکند؛ بنابراین du -sh /var/lib/dsh را به روشی اضافه کنید که از قبل برای monitor کردن دیسک استفاده میکنید.
اگر هدف شما یک agent تعاملی است که به آن attach و از آن detach میشوید، service ساختار مناسبی نیست و اجرای agent در یک نشست پایدار tmux انتخاب بهتری است. زمانی dsh را بهصورت unit اجرا کنید که میخواهید همیشه بالا و از طریق tunnel قابل دسترسی باشد.
حالتهای شکست و پیامهایی که مشاهده خواهید کرد
status=203/EXEC. سیستم systemd نتوانسته است فایل را اجرا کند و لاگها Failed to locate executable /usr/local/bin/dsh: No such file or directory را نشان میدهند. مسیر موجود در ExecStart= با آنچه command -v dsh چاپ کرده است، مطابقت ندارد. این همان خطایی است که Type=exec در زمان systemctl start به جای پنهان کردن، گزارش میدهد.
status=217/USER. سیستم systemd در تعیین یا تغییر اعتبارنامههای کاربری از User= و Group=، یا در تنظیم فضای نام کاربری (user namespacing) شکست خورده است. دلیل معمول برای این واحد، وجود نداشتن حساب کاربری است. با استفاده از id dsh این موضوع را تأیید کنید.
status=200/CHDIR. فایل WorkingDirectory= وجود ندارد یا کاربر سرویس نمیتواند به آن وارد شود. دستور sudo -u dsh ls /var/lib/dsh/workspace آن را مستقیماً بازتولید میکند.
Error: listen EADDRINUSE: address already in use 127.0.0.1:3080. چیزی در حال حاضر پورت را اشغال کرده است؛ معمولاً به این دلیل که اجرای npx در ترمینال دیگری باز مانده است. دستور sudo ss -lntp | grep 3080 نام آن پردازش را مشخص میکند.
EACCES: permission denied به همراه یک مسیر. مالکیت در مسیر /var/lib/dsh اشتباه است؛ معمولاً به این دلیل که اولین اجرا با دسترسی root یا با HOME اشتباه انجام شده است. دستور sudo chown -R dsh:dsh /var/lib/dsh این مشکل را برطرف میکند.
Start request repeated too quickly. واحد به محدودیت نرخ شروع (start rate limit) رسیده و متوقف شده است. خطای اصلی در خطوط بالای آن قرار دارد. پیش از تلاش مجدد، دستور sudo systemctl reset-failed dsh را اجرا کنید.
واحد active (running) است اما مرورگر چیزی نشان نمیدهد. بررسی را روی VPS انجام دهید: اگر curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/ یک کد وضعیت در آنجا چاپ میکند، یعنی listener روی VPS پاسخ میدهد؛ بنابراین در مرحله بعد port forward را بررسی کنید. آن کد ثابت نمیکند که همه چیز بارگذاری شده است؛ upstream میگوید خرابی پلاگینهای اختیاری مانع از اعلام آمادگی (readiness) نمیشود، بنابراین برای یافتن خطاهای پلاگین، journalctl -u dsh -n 200 --no-pager را نیز بخوانید. کد 401 در مرورگر به این معنی است که کوکی نشست (session cookie) معتبر ندارد و URL نیز فاقد launch token معتبر است؛ یا به این دلیل که URL خام را باز کردهاید یا توکن مربوط به پیش از آخرین راهاندازی مجدد است. URLای را که پردازش فعلی چاپ کرده است، باز کنید.
ارتقای آگاهانه
پین کردن (Pinning) به این معناست که ارتقا عملی است که شما انجام میدهید، نه اتفاقی که برای شما میافتد. ابتدا یادداشتهای انتشار (release notes) را مطالعه کنید، زیرا هشدار خودِ توسعهدهنده درباره تغییرات ناسازگار، دقیقاً همان دلیلی است که باید نسخه را پین کنید. از دایرکتوری state نسخه پشتیبان تهیه کنید و سپس نسخه را تغییر دهید:
sudo systemctl stop dsh
sudo tar czf /root/dsh-home-$(date +%F).tgz -C /var/lib/dsh harness
sudo npm install -g @deepseek-ai/dsh@0.2.1-rc.2
sudo systemctl start dsh
journalctl -u dsh -n 50 --no-pagerبازگشت به نسخه قبل (Rolling back) همان فرآیند npm install -g با نسخه قدیمی است، به اضافه بازیابی آن فایل tarball که تنها در صورتی ممکن است که از آن نسخه پشتیبان گرفته باشید. یک runtime برای عامل در مرحله پیشنمایش (preview-stage)، دقیقاً همان نرمافزاری است که ارتقای آن میتواند فرمت فایل پیکربندی شما را بدون اطلاع قبلی بازنویسی کند.
FAQ
چرا وقتی نشست SSH خود را میبندم، dsh متوقف میشود؟
زیرا npx @deepseek-ai/dsh web یک پردازش پیشزمینه است که متعلق به نشست ورود شماست؛ بنابراین با پایان نشست، این پردازش نیز خاتمه مییابد. در مقابل، یک unit در systemd متعلق به سیستم init است و به همین دلیل پس از قطع اتصال شما به کار خود ادامه میدهد و پس از reboot نیز دوباره اجرا میشود. sudo systemctl enable --now dsh مجموعهای از دو مرحله است که هر دو قابلیت را برای شما فراهم میکند: enable برای اجرای خودکار پس از reboot و --now برای شروع آن در همین نشست.
آیا باید برای dsh از Type=simple استفاده کنم یا Type=exec؟
Type=exec. برنامه dsh در پیشزمینه اجرا میشود و هرگز fork نمیکند، بنابراین هر دو گزینه کار میکنند؛ اما Type=exec باعث میشود systemd پیش از اعلام موفقیتآمیز بودن شروع سرویس، منتظر بماند تا execve() با موفقیت اجرا شود. در این حالت، اگر مسیر اشتباهی در ExecStart= باشد، systemctl start با خطای status=203/EXEC در مقابل شما شکست میخورد. با استفاده از Type=simple، همان اشتباه وضعیت موفقیت برمیگرداند و خطا در journal پنهان میماند. گزینههای Type=forking و Type=notify هر دو در اینجا اشتباه هستند و باعث میشوند سرویس تا زمان انقضای TimeoutStartSec (که بهصورت پیشفرض 90 ثانیه است) معلق بماند.
چگونه رابط کاربری وب dsh را از لپتاپ خود باز کنم؟
پورت را از طریق SSH فوروارد کنید: ssh -N -L 3080:127.0.0.1:3080 you@your-vps، سپس URLای که dsh در زمان شروع چاپ کرده است (و میتوانید آن را با journalctl -u dsh پیدا کنید) را در مرورگر خود باز کنید. آن URL حاوی توکن راهاندازی است و مرورگری که وارد نشده باشد، بدون آن توکن خطای 401 دریافت میکند. پس از ورود، کوکی نشست بهصورت پیشفرض 30 روز اعتبار دارد و با restart شدن سرویس از بین نمیرود. سرویس را روی تنظیم پیشفرض loopback باقی بگذارید. برنامه dsh استفاده از wildcard مانند --host 0.0.0.0 را بهعنوان یک آدرس نامشخص رد میکند؛ اگرچه یک آدرس محلی مشخص را میپذیرد، اما bind کردن روی آدرسی غیر از loopback باعث میشود سرویس HTTP ساده ارائه دهد (مگر اینکه TLS را تنظیم کنید). این کار باعث میشود توکن راهاندازی برای عاملی که دستورات shell را در شبکه اجرا میکند، بهصورت متن ساده (cleartext) ارسال شود.
آیا میتوانم dsh را بهعنوان root اجرا کنم تا مجوزها ساده بمانند؟
خیر. این ابزار برای اجرای دستورات و نوشتن فایلها طراحی شده است، بنابراین هر امتیازی که سرویس داشته باشد، عامل (agent) نیز همان امتیازات را خواهد داشت. یک حساب کاربری سیستمی با useradd --system --shell /usr/sbin/nologin dsh ایجاد کنید، مالکیت /var/lib/dsh را به آن بدهید و NoNewPrivileges=true را به unit اضافه کنید. اگر پس از آن با EACCES: permission denied مواجه شدید، دلیل معمول آن اجرای قبلی برنامه با کاربر root است که فایلهایی با مالکیت root باقی گذاشته است؛ sudo chown -R dsh:dsh /var/lib/dsh این مشکل را برطرف میکند.
کدام نسخه از dsh را باید در unit ثابت (pin) کنم؟
هر نسخهای که npm view @deepseek-ai/dsh version هنگام راهاندازی سرویس گزارش میدهد، با استفاده از npm install -g @deepseek-ai/dsh@<that version> نصب شده و در جایی که بعداً آن را پیدا کنید، ثبت شده باشد. نسخه 0.1.0-rc.7 در 18 اوت 2026، نسخه 0.2.0-rc.2 در 11 اکتبر 2026 و نسخه 0.2.1-rc.2 در 27 اکتبر 2026 جاری بودند و next در حال حاضر در نسخه 0.2.1-rc.4 است. در 4 نوامبر 2026، هر دو نسخه latest و next به 0.2.1-rc.5 اشاره دارند. نسخههای قدیمی مانند 0.1.0-rc.7 احراز هویت مرورگر ندارند، بنابراین برای پروفایل وب از آنها استفاده نکنید. نکته مهم شماره نسخه نیست، بلکه این است که npx بدون تعیین نسخه، پکیج را در زمان شروع resolve میکند؛ بنابراین یک restart خودکار ممکن است بدون اطلاع شما، نسخه برنامه را به نسخهای با فرمت پیکربندی متفاوت تغییر دهد.