inogen/deployment/INSTALL.md

123 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# راهنمای نصب دستی Inogen برای مشتری
در نمونه‌های زیر، سرور SQL برابر `SQL-SERVER-01`، دیتابیس جدید برابر `Inogen_CompanyA`، دامنهٔ فرانت برابر `app.example.com` و دامنهٔ API برابر `api.example.com` است. این مقدارها را با مقدار واقعی خود جایگزین کنید. فرمان‌ها را از ریشهٔ بستهٔ استخراج‌شده اجرا کنید.
## ۱. سرور و فایل‌ها را آماده کنید
1. روی Windows Server، IIS با قابلیت‌های Static Content و Default Document، افزونه URL Rewrite و .NET Hosting Bundle سازگار با API را نصب کنید.
2. برای دامنه‌های فرانت و API رکورد DNS تنظیم کنید. گواهی HTTPS معتبر هر دامنه را روی سرور IIS نصب کنید؛ گواهی CDN به‌تنهایی گواهی IIS نیست.
3. ZIP را در پوشه‌ای مانند `C:\Inogen` استخراج کنید. پوشه‌های `frontend` و `backend` را کنار هم نگه دارید؛ فرمان‌های نصب را از ریشهٔ بسته اجرا کنید.
## ۲. دیتابیس و حساب‌ها را آماده کنید
1. در SQL Server یک دیتابیس خالی با نام واقعی استقرار، مانند `Inogen_CompanyA`، ایجاد کنید.
2. در SSMS به همان نمونهٔ SQL Server که دیتابیس را در آن ساخته‌اید، با حساب مدیر وصل شوید. از بخش `Security > Logins` حساب SQL به نام `inogen_migrator` را بسازید یا وجود آن را بررسی کنید. در یک پنجرهٔ Query همان اتصال، نام دیتابیس را در فرمان زیر جایگزین و آن را اجرا کنید تا کاربر دیتابیس ساخته شود و مجوز اجرای migration بگیرد:
```sql
USE [Inogen_CompanyA]; IF USER_ID(N'inogen_migrator') IS NULL CREATE USER [inogen_migrator] FOR LOGIN [inogen_migrator]; IF IS_ROLEMEMBER(N'db_owner', N'inogen_migrator') <> 1 ALTER ROLE [db_owner] ADD MEMBER [inogen_migrator];
```
حساب جداگانهٔ `inogen_runtime` را برای API بسازید؛ پس از اجرای migration به آن مجوزهای `SELECT`، `INSERT`، `UPDATE` و `DELETE` روی schema `inogen` بدهید. به حساب runtime مجوز تغییر ساختار ندهید.
3. پیش از اجرای migration، یک اتصال جدید در SSMS با SQL Authentication و حساب `inogen_migrator` به همان نمونهٔ SQL باز کنید. فرمان زیر را با نام دیتابیس واقعی اجرا کنید. مقدارهای `IsDbOwner` و `CanCreateTable` باید هر دو `1` باشند. اگر اتصال برقرار نشد یا یکی از مقدارها `1` نبود، نگاشت کاربر، نقش و نام نمونهٔ SQL را با مدیر سرور اصلاح کنید و سپس این بررسی را تکرار کنید:
```sql
USE [Inogen_CompanyA]; SELECT @@SERVERNAME AS SqlServer, DB_NAME() AS DatabaseName, ORIGINAL_LOGIN() AS LoginName, USER_NAME() AS DatabaseUser, IS_MEMBER(N'db_owner') AS IsDbOwner, HAS_PERMS_BY_NAME(DB_NAME(), N'DATABASE', N'CREATE TABLE') AS CanCreateTable;
```
4. گواهی TLS سرور SQL را روی سرور برنامه مورد اعتماد قرار دهید. رشته‌های اتصال را با `Encrypt=True;TrustServerCertificate=False` تنظیم کنید.
## ۳. تنظیمات را ثبت و migration را اجرا کنید
1. در `backend\appsettings.Production.json`، مقدارهای نمونهٔ `AllowedServers`، `AllowedDatabases` و `FrontendOrigins` را با سرور SQL، دیتابیس مقصد و نشانی فرانت واقعی جایگزین کنید. مقدار `ApplyMigrationsOnStartup` را `false` نگه دارید. مقدار `TargetDatabase` فقط نمونه است؛ رمز `CHANGE_ME` را در فایل به رمز واقعی تبدیل نکنید. رشتهٔ اتصال واقعی را در گام IIS، برای App Pool API ثبت کنید.
2. در `frontend\config\runtime-config.js` نشانی API را ثبت کنید:
```javascript
window.INOGEN_CONFIG = { apiBaseUrl: "https://api.example.com/api/v1" };
```
فایل را در پوشهٔ `frontend` **نسخهٔ نصب‌شده روی سرور** نیز بررسی کنید؛ مقدار `/api/v1` فقط زمانی درست است که API و فرانت روی یک دامنه و از همان مسیر منتشر شده باشند. برای دو دامنهٔ جدا، نشانی کامل HTTPS دامنهٔ API را مانند نمونهٔ بالا بگذارید. در `backend\appsettings.Production.json` نیز نشانی واقعی دامنهٔ فرانت را در `FrontendOrigins` ثبت کنید.
3. در PowerShell، پس از اصلاح `AllowedServers` و `AllowedDatabases` در فایل تنظیمات، فرمان زیر را از ریشهٔ بسته اجرا کنید. نام حساب SQL را جایگزین کنید؛ اسکریپت نام سرور و دیتابیس را از همان فایل می‌خواند و رمز را جداگانه درخواست می‌کند:
```powershell
.\migrate-target.ps1 -SqlUser 'inogen_migrator'
```
فقط پس از دیدن `Target migrations applied.` ادامه دهید و همین پنجرهٔ PowerShell را برای ساخت حساب مدیر باز نگه دارید. migration ساختار دیتابیس را ایجاد می‌کند و دادهٔ قدیمی را منتقل نمی‌کند. اگر گواهی SQL فقط در محیط تست مورد اعتماد نیست، می‌توانید موقتاً `-TrustServerCertificate` را به انتهای همین فرمان اضافه کنید.
اگر خطای `SQL error 262: CREATE TABLE permission denied` دیدید، migration را متوقف کنید؛ گام ۲ و ۳ بخش «دیتابیس و حساب‌ها» را روی همان نمونهٔ SQL و همان دیتابیس تکرار کنید. پیام `Target guard passed` فقط نام مقصد را بررسی می‌کند و تأیید مجوز SQL نیست. پس از اینکه هر دو مقدار بررسی مجوز `1` شدند، فرمان migration را دوباره اجرا کنید. اگر خطای گواهی نامعتبر دیدید، گواهی SQL را روی سرور برنامه مورد اعتماد قرار دهید؛ گزینهٔ `-TrustServerCertificate` فقط برای تست داخلی است.
4. پس از migration، در SSMS مجوز حساب runtime را روی دیتابیس مقصد ثبت کنید:
```sql
USE [Inogen_CompanyA]; IF USER_ID(N'inogen_runtime') IS NULL CREATE USER [inogen_runtime] FOR LOGIN [inogen_runtime]; GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::[inogen] TO [inogen_runtime];
```
## ۴. سایت‌های IIS را دستی ایجاد کنید
1. در IIS Manager دو Application Pool به نام `Inogen-Frontend` و `Inogen-Api` بسازید و `.NET CLR Version` را برای هر دو روی `No Managed Code` بگذارید.
2. سایت فرانت را به مسیر فیزیکی `C:\Inogen\frontend` و Pool اول وصل کنید. سایت API را به `C:\Inogen\backend` و Pool دوم وصل کنید. اگر مسیر استخراج متفاوت است، همان مسیر واقعی را وارد کنید.
3. برای هر سایت binding از نوع `https` روی پورت `443` و Host name همان دامنه با SNI بسازید و گواهی همان دامنه را انتخاب کنید. اگر از ابر آروان استفاده می‌کنید، HTTPS از آروان تا سرور مبدأ را نیز تنظیم کنید.
4. به `IIS AppPool\Inogen-Api` روی `backend\data` و زیرپوشه‌های آن مجوز Modify بدهید.
5. رشتهٔ اتصال حساب runtime را با نام `ConnectionStrings__TargetDatabase` در **متغیرهای محیطی App Pool API** ثبت کنید. نمونهٔ مقدار در `appsettings.Production.json` آمده است؛ رمز واقعی را در آن فایل ننویسید. پس از ساخت Pool، در PowerShell مدیر فرمان زیر را اجرا کنید. اسکریپت نام سرور و دیتابیس را از فایل تنظیمات می‌خواند و رمز را جداگانه می‌پرسد:
```powershell
.\set-iis-runtime-connection.ps1 -SqlUser 'inogen_runtime' -AppPoolName 'Inogen-Api'
```
این مقدار در تنظیمات IIS ذخیره می‌شود؛ دسترسی مدیران سرور به آن را محدود کنید. اگر نام Pool را تغییر داده‌اید، مقدار `-AppPoolName` را عوض کنید. در محیط تست، اگر گواهی SQL هنوز مورد اعتماد نیست، گزینهٔ `-TrustServerCertificate` را فقط موقتاً به فرمان اضافه کنید.
6. از خود سرور، `https://api.example.com/health` و سپس `https://api.example.com/api/v1/deployment/profile` را باز کنید. پاسخ اول باید کد `200` و پاسخ دوم باید یک شیء JSON شامل `company`، `branding` و `activation` باشد. سپس نشانی فرانت را باز کنید. اگر فرانت پیام «تنظیمات استقرار در دسترس نیست» نشان داد، ابتدا `frontend\config\runtime-config.js` را بررسی کنید و سپس در ابزار Developer Tools مرورگر، وضعیت درخواست `/api/v1/deployment/profile` را ببینید. اگر درخواست به دامنهٔ اشتباه می‌رود، نشانی API را در همان فایل اصلاح و صفحه را با بارگذاری کامل دوباره باز کنید؛ اگر درخواست از دامنهٔ درست خطای شبکه یا CORS دارد، HTTPS دامنهٔ API و مقدار `FrontendOrigins` را بررسی کنید.
## ۵. سامانه را فعال و مدیر را ایجاد کنید
1. نشانی فرانت را مانند `https://app.example.com/admin` باز کنید. اگر صفحهٔ فعال‌سازی نمایش داده شد، شناسهٔ ۶۴ کاراکتری سرور را کپی و برای صادرکنندهٔ کد ارسال کنید. کد دریافتی را در همان صفحه ثبت کنید.
2. در همان نشست PowerShell گام ۳، حساب مدیر را روی همان دیتابیس بسازید. اگر PowerShell را بسته‌اید، ابتدا اتصال را در نشست جدید با فرمان زیر دوباره آماده کنید؛ `-ConfigureOnly` migration را تکرار نمی‌کند:
```powershell
.\migrate-target.ps1 -SqlUser 'inogen_migrator' -ConfigureOnly
```
اگر فقط در محیط تست گواهی SQL هنوز مورد اعتماد نیست، به همین فرمان `-TrustServerCertificate` را هم اضافه کنید. سپس در همان پنجره حساب مدیر را بسازید:
```powershell
.\initialize-admin.ps1 -DisplayName 'مدیر سامانه'
```
رمز مدیر باید حداقل ۱۲ نویسه، حرف بزرگ، حرف کوچک، رقم و نویسهٔ ویژه داشته باشد. نام کاربری خروجی را ثبت کنید و رمز را جداگانه و امن تحویل دهید. حساب مدیر با رمز پیش‌فرض وجود ندارد.
پس از فعال‌سازی و اولین ورود مدیر، اگر تنظیمات شرکت هنوز کامل نشده باشد، صفحهٔ «تنظیمات استقرار» به‌صورت خودکار نمایش داده می‌شود. برای بازکردن آن در دفعات بعد، نشانی `https://app.example.com/admin/deployment-settings` را دستی در نوار آدرس مرورگر وارد کنید؛ این صفحه در منوی پنل نمایش داده نمی‌شود و فقط حساب مدیر به آن دسترسی دارد. صفحهٔ ورود کد فعال‌سازی فقط کد را دریافت می‌کند؛ مشخصات شرکت و واحدها در صفحهٔ جداگانهٔ تنظیمات استقرار ثبت می‌شوند.
### فایل‌های لازم برای راه‌اندازی شرکت جدید
پیش از ورود به صفحهٔ تنظیمات استقرار، این فایل‌ها و اطلاعات را از شرکت دریافت کنید:
- **لوگوی ورود داشبورد:** فایل SVG مخصوص صفحهٔ ورود بخش گزارش‌ها، حداکثر ۲ مگابایت.
- **لوگوی ورود ادمین:** فایل SVG مخصوص صفحهٔ ورود پنل مدیریت، حداکثر ۲ مگابایت. اگر قرار است هر دو صفحه یک نشان داشته باشند، همان فایل SVG را برای هر دو جایگاه انتخاب کنید.
- **تصویر هر واحد یا شرکت مرتبط در داشبورد، در صورت نیاز:** برای هر جایگاه یک فایل PNG، GIF، WebP یا SVG، حداکثر ۸ مگابایت. اگر تصویر اختصاصی ندارید، تصویر پیش‌فرض همان جایگاه باقی می‌ماند. برای PNG، عرض و ارتفاع نباید از ۴۰۹۶ پیکسل بیشتر باشد.
- **نام رسمی شرکت و فهرست واحدها:** نامی که باید در سامانه نمایش داده شود، نام هر واحد یا شرکت مرتبط، تعداد واحدها (یک تا شش)، و ترتیب دلخواه نمایش آن‌ها.
فایل‌های SVG باید معتبر و بدون کد اجرایی یا ارجاع خارجی باشند. لوگوی مرکز نمودار زیست‌بوم فایل جداگانه نمی‌خواهد؛ از یکی از دو لوگوی ورود انتخاب می‌شود. در نسخهٔ فعلی صفحه، بارگذاری لوگوی محصول یا favicon از این بخش انجام نمی‌شود.
### تکمیل صفحهٔ «تنظیمات استقرار»
1. **فعال‌سازی:** وضعیت فعال‌بودن، نسخهٔ پروفایل، زمان صدور، شناسهٔ سرور و کد ثبت‌شده را ببینید. کد فعال‌سازی و شناسه از این صفحه قابل ویرایش نیستند.
2. **هویت شرکت:** نام کامل شرکت را همان‌طور که باید در بخش‌های سامانه دیده شود وارد کنید.
3. **لوگوهای استقرار:** برای «لوگوی SVG ورود داشبورد» و «لوگوی SVG ورود ادمین» فایل مربوط را جداگانه انتخاب و بارگذاری کنید. هر فایل، لوگوی فعال همان جایگاه را جایگزین می‌کند.
4. **لوگوی مرکز زیست‌بوم:** مشخص کنید در مرکز نمودار زیست‌بوم، لوگوی ورود داشبورد نمایش داده شود یا لوگوی ورود ادمین.
5. **واحدهای داشبورد:** با «افزودن واحد» یا دکمهٔ حذف، تعداد واحدها را بین یک تا شش تنظیم کنید. الگوی چیدمان مناسب را انتخاب کنید؛ نام هر واحد/شرکت مرتبط را وارد کنید و جایگاه‌ها را با کشیدن یا فهرست «انتقال به جایگاه» مرتب کنید. در صورت نیاز، تصویر هر واحد را با «جایگزینی تصویر» بارگذاری کنید یا با «پیش‌فرض» به تصویر اولیه برگردانید.
6. **اطلاعات و نمودارها:** عنوان سری کاهش هزینه را وارد کنید، شاخص‌های نمایشی مشترک واحدها (افزایش درآمد، کاهش هزینه، افزایش ظرفیت) را انتخاب کنید و دربارهٔ نمایش سری درآمد در نمودار مقایسه‌ای تصمیم بگیرید.
7. در پایان، **«ذخیره تنظیمات»** را بزنید. پس از بارگذاری تصویر اختصاصی واحد، این ذخیره‌کردن برای نهایی‌شدن انتخاب آن ضروری است. صفحه‌های گزارش و مدیریت را دوباره بارگذاری کنید و نام‌ها، لوگوها، تعداد واحدها و ترتیب آن‌ها را ببینید.
اگر ساخت مدیر ناموفق بود، مرحلهٔ اعلام‌شده در خطای ابزار را بخوانید. برای خطای `Identity validation failed`، کد خطای سیاست رمز یا نام کاربری را اصلاح و فرمان را دوباره اجرا کنید. اگر نشست PowerShell عوض شده است، ابتدا فرمان `migrate-target.ps1` را با `-ConfigureOnly` در همان نشست اجرا کنید و سپس ساخت مدیر را تکرار کنید. اگر خطا در مرحلهٔ `create roles` یا `assign administrator role` رخ داد، مجوز حساب migration را روی دیتابیس مقصد بررسی کنید؛ حساب API را برای این فرمان به کار نبرید.
## ۶. نصب را بررسی کنید
1. نشانی پنل مدیر را با دامنهٔ واقعی فرانت، مانند `https://app.example.com/admin`، باز کنید و با حساب مدیری که در گام ۵ ساخته‌اید وارد شوید. نشانی دامنهٔ API صفحهٔ ورود مدیر ندارد. پاسخ فرانت و API را بررسی کنید.
2. روی نقطهٔ پایان HTTPS، TLS 1.0 و 1.1 و cipherهای CBC را غیرفعال کنید. برای Windows Server می‌توانید `configure-windows-tls.ps1` را ابتدا برای پیش‌نمایش و سپس در بازهٔ نگهداری با `-Apply` اجرا کنید. تنظیمات ابر آروان را در پنل آن انجام دهید.
3. متغیرهای موقت نشست نصب را پاک کنید:
```powershell
Remove-Item Env:INOGEN_TARGET_CONNECTION,Env:INOGEN_TARGET_ALLOWED_SERVER,Env:INOGEN_TARGET_ALLOWED_DATABASE -ErrorAction SilentlyContinue
```