Update migration document: new installation and mariadb guide#5
Update migration document: new installation and mariadb guide#5M03ED merged 2 commits intoPasarGuard:mainfrom
Conversation
WalkthroughDocumentation for Marzban → PasarGuard migration was rewritten in English, Persian, Russian, and Chinese to add two distinct migration flows (current installation vs. new installation), expand SQLite/MySQL/MariaDB-specific steps, rename Marzban references to PasarGuard, and add detailed Docker, SSL, rollback, and post-migration verification guidance. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Admin as Admin
participant Docs as Migration Guide
participant Src as Old Marzban Install
participant Dest as New PasarGuard Install
participant DB as Database (SQLite/MySQL/MariaDB)
Note right of Docs #DFF2E6: Dual migration paths\n(Current vs New)
Admin->>Docs: Read guide & choose path
alt Current installation
Admin->>Src: Stop services, rename dirs, update .env
Src->>DB: Export / move DB files
Admin->>Src: Start PasarGuard in-place
DB-->>Admin: DB migrated (SQLite/MySQL/MariaDB steps)
else New installation
Admin->>Dest: Install PasarGuard fresh
Admin->>DB: Export from Marzban
Admin->>Dest: Import DB, configure SSL, update .env
Dest->>Admin: Start services, verify panel
end
Admin->>Docs: Follow rollback/troubleshoot if needed
Note over Admin,Docs #FFF4D9: Verification, backups, and rollback steps highlighted
Estimated code review effort🎯 4 (Complex) | ⏱️ ~40 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
content/docs/zh/migration/marzban.mdx (1)
114-146: Database driver update examples need clarification in SQLite tabWhile the old and new SQLite URLs are provided, the Chinese text could better emphasize why the driver change is necessary (moving from synchronous to async SQLite driver for performance). The examples are correct, but the educational context is minimal.
content/docs/en/migration/marzban.mdx (1)
653-653: Acknowledged: Minor style variation on "need to edit"LanguageTool flags repetition of "You need to..." pattern in nearby sentences (lines 651-653). While the content is clear, varying the phrasing slightly could improve readability. However, this is a very minor point and current wording is acceptable for instructional clarity.
content/docs/ru/migration/marzban.mdx (1)
166-200: Tab headers mix English and Russian inconsistentlyLines 166 and 179 use English tab titles ("XRAY_SUBSCRIPTION_TEMPLATE", "Xray-Config Certificate Directories") while the content headers (lines 167, 180) are translated to Russian. For consistency, tab values should remain in English for code references, but the section headers below them should use Russian text. Current approach is acceptable but could be clearer.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
public/images/migration/drop-mysql-tables.pngis excluded by!**/*.pngpublic/images/migration/edit-mysql-database-1.pngis excluded by!**/*.pngpublic/images/migration/edit-mysql-database-2.pngis excluded by!**/*.png
📒 Files selected for processing (4)
content/docs/en/migration/marzban.mdx(11 hunks)content/docs/fa/migration/marzban.mdx(10 hunks)content/docs/ru/migration/marzban.mdx(9 hunks)content/docs/zh/migration/marzban.mdx(13 hunks)
🧰 Additional context used
🪛 LanguageTool
content/docs/en/migration/marzban.mdx
[grammar] ~157-~157: Ensure spelling is correct
Context: ...certificate directories from marzban to pasarguard in your xray_config.json file: ```ba...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~653-~653: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...efully: - Edit the database file: You need to edit your MySQL or MariaDB database fil...
(REP_NEED_TO_VB)
content/docs/zh/migration/marzban.mdx
[uncategorized] ~10-~10: 您的意思是“"账"户”？
Context: ...beta-3 及以下版本。 本指南将帮助您将数据、设置和用户帐户从 Marzban 迁移到 PasarGuard，且不会丢失任何内容。 解释...
(ZHANG7_ZHANG8)
content/docs/fa/migration/marzban.mdx
[misspelling] ~16-~16: اشتباه محتمل املائی پیداشده: دستورها.
Context: ...به سرور جدید نیست، ولی کمی پیچیدهتره و دستورات بیشتری داره. - [PasarGuard مهاجرت با ن...
(FA_SIMPLE_REPLACE)
[misspelling] ~20-~20: اشتباه محتمل املائی پیداشده: دستورها.
Context: ...ب-جدید) این روش راحتتر و سریعتره، با دستورات کمتر. ولی به سرور جدید نیاز داره و بعضی...
(FA_SIMPLE_REPLACE)
[misspelling] ~450-~450: اشتباه محتمل املائی پیداشده: دستورها.
Context: ...اسارگارد وارد بشه. >
(FA_SIMPLE_REPLACE)
[misspelling] ~727-~727: اشتباه محتمل املائی پیداشده: دستورها.
Context: ...رید (Permission Denied)**: مطمئن شید که دستورات رو با دسترسیهای مناسب (sudo در صورت نی...
(FA_SIMPLE_REPLACE)
🔇 Additional comments (15)
content/docs/zh/migration/marzban.mdx (4)
14-20: Dual migration paths clearly structuredThe introduction of two migration methods is well-organized with clear descriptions of complexity tradeoffs (existing installation: more commands but no new server; new installation: fewer commands but requires new server). This provides users with a good decision framework.
215-392: Docker Compose before/after structure with three databases is comprehensiveThe accordion-based presentation for SQLite, MySQL, and MariaDB provides clear, side-by-side comparisons of configuration changes. All service names, image references, volume paths, and database names are consistently updated from "marzban" to "pasarguard." This structure effectively communicates the migration scope.
461-502: Database export/import process uses both mysqldump and mariadb-dump correctlyThe migration steps properly distinguish between MySQL (
mysqldump,mysql) and MariaDB (mariadb-dump,mariadb) commands. The fallback instruction at line 479 (using "marzban" user with MYSQL_PASSWORD) adds helpful error recovery guidance.
7-7: Fix spelling: "帐户" should be "账户"The static analysis tool flagged this as a standard Chinese spelling issue. "账户" is the preferred modern term for "account."
-本指南适用于 Marzban beta-3 及以下版本。 +本指南适用于 Marzban beta-3 及以下版本。Likely an incorrect or invalid review comment.
content/docs/en/migration/marzban.mdx (4)
157-157: Minor style inconsistency: Consider consistency with MySQL examplesThe phrasing "Update the certificate directories from marzban to pasarguard in your
xray_config.jsonfile" is clear and grammatically correct. The LanguageTool flag appears to be a false positive on spelling/orthography. No change needed.
12-20: Two migration methods explanation is clear and actionableThe dual-path introduction effectively communicates pros/cons: existing installation preserves settings but is more complex; new installation is simpler but requires manual reconfiguration. Users can make an informed choice. This aligns with PR objectives.
437-447: SQLite database migration step is appropriately briefFor SQLite migrations, the new installation path correctly instructs users to simply copy the
db.sqlite3file to/var/lib/pasarguard/. This is accurate and sufficient.
506-520: Database import process correctly specifies MySQL ROOT PASSWORD replacementThe instructions clearly indicate that
MYSQL_ROOT_PASSWORDmust be replaced with the actual value from the.envfile. Both MySQL and MariaDB variants are provided with appropriate commands (mysqlvsmariadb).content/docs/ru/migration/marzban.mdx (2)
12-20: Dual migration paths clearly described in RussianThe explanation of two migration methods is well-translated and provides the same decision framework as English/Chinese versions. The tradeoffs are clear: current installation is complex but preserves settings; new installation is simple but requires manual reconfiguration.
447-459: MySQL/MariaDB startup commands properly distinguished with tabsThe distinction between MySQL and MariaDB services is correctly made with separate Docker Compose commands. The tab structure clearly shows the service name differences.
content/docs/fa/migration/marzban.mdx (5)
116-127: SQLite section properly uses RTL wrapperThe SQLite database section is correctly wrapped in
<div dir="rtl">to ensure proper right-to-left text rendering. The old/new examples are clearly presented in Persian with code blocks properly formatted.
12-20: Dual migration paths explanation is well-structured in PersianThe description of two migration methods is clear and provides the same decision framework as English/Chinese/Russian versions. Users understand the tradeoff between complexity (current installation) vs. simplicity (new installation).
16-16: LanguageTool flags for "دستورات" appear to be alternative spelling suggestionsLanguageTool flags multiple instances of "دستورات" (commands) suggesting these are "misspellings," but this appears to be a false positive or alternative form detection. "دستورات" is the standard Persian plural for "commands." If LanguageTool is suggesting "دستورات" → "دستورات" (same form), these are false positives. Unless there's a specific style guide requiring an alternative form, no change is needed.
Also applies to: 20-20, 450-450, 727-727
225-401: Docker Compose accordions properly handle RTL formatting for PersianThe three-accordion structure for SQLite, MySQL, and MariaDB is implemented without explicit RTL wrappers on the YAML code blocks themselves, which is appropriate since code is typically left-to-right. The surrounding Persian text and before/after labels are clearly formatted. This structure effectively communicates all necessary configuration changes across database backends.
444-583: Database migration section properly separates MySQL and MariaDB proceduresThe export/import process is clearly distinguished between MySQL (mysqldump, mysql commands) and MariaDB (mariadb-dump, mariadb commands). Tab structure makes it easy to switch between database types. The critical step of editing database names in SQL file (line 507-511) is clearly explained with both the sed command and manual editing options.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
content/docs/ru/migration/marzban.mdx (1)
612-620: Enhance emphasis on manual post-migration configuration.The callout at lines 612-620 correctly notes that settings won't be auto-migrated when using the new installation path. However, this is critical information that directly affects users' experience. Consider adding explicit examples (e.g., Telegram bot, URL prefix) of the manual steps they'll encounter, or cross-reference the panel configuration documentation more prominently to reduce confusion.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/docs/ru/migration/marzban.mdx(9 hunks)
🔇 Additional comments (2)
content/docs/ru/migration/marzban.mdx (2)
752-752: Clarify Xray-Core reference in post-migration section.Line 752 states "Сам PasarGuard не использует Xray-Core," but the document extensively references Xray configuration (xray_config.json, Xray templates, certificate directories) in the migration steps. This could confuse users about whether they need to manage Xray settings during migration.
Please clarify what role Xray-Core plays in PasarGuard or rephrase this sentence to better explain the relationship between PasarGuard and Xray-Core infrastructure.
643-645: Verify SQLite migration simplicity.Line 645 suggests simply copying the SQLite database file (
db.sqlite3) from Marzban to PasarGuard. This may oversimplify the migration—schema or initialization differences between versions could cause the database to be unusable or cause runtime errors.Consider adding a verification step to validate the database after import, or clarifying any schema compatibility assumptions.
2 participants
Major changes:
Minor changes:
About the docker compose examples:
I didn't use the provided examples in the scripts repo, which have MySQL environment variable in them, because it introduces some problems like many users not having the needed variables in their .env and the extra step to change the variables for those who have them.
These examples should work with both docker compose configs that many users use (with or without MySQL environment variables)
However, if you think adding some optimizations (such as --character_set_server=utf8mb4 command or similar) is necessary, I can include them.
Summary by CodeRabbit