‏WSO2 چیست؟ راهنمای جامع نصب API Manager با Docker، پیکربندی SSL و استقرار Production

WSO2 چیست و چه محصولاتی دارد؟

WSO2 در سال ۲۰۰۵ در سریلانکا به‌دست سانجیوا ویراوارانا (Sanjiva Weerawarana) و همکارانش تأسیس شد؛ تیمی که سابقه‌ی پررنگی در پروژه‌های بنیاد نرم‌افزار آپاچی داشت. این شرکت امروز خود را بزرگ‌ترین فروشنده‌ی مستقل نرم‌افزارهای متن‌باز در حوزه‌ی مدیریت API، یکپارچه‌سازی و مدیریت هویت معرفی می‌کند و بیش از ۸۰۰ کارمند در کشورهایی مانند آمریکا، انگلستان، آلمان، هند، استرالیا، برزیل، امارات و سریلانکا دارد. در سال ۲۰۲۴ صندوق سرمایه‌گذاری سوئدی EQT مالکیت WSO2 را به دست گرفت و ویراوارانا همچنان مدیرعامل شرکت باقی ماند.

وب‌سایت رسمی شرکت، wso2.com، نقطه‌ی شروع همه‌چیز است: دانلود محصولات، مستندات هر محصول (مثل apim.docs.wso2.com و is.docs.wso2.com)، وبلاگ فنی، جدول پشتیبانی نسخه‌ها (Support Matrix) و اطلاعات اشتراک تجاری. کد منبع محصولات قابل‌نصب روی GitHub و با مجوز Apache 2.0 منتشر می‌شود.

خانواده‌ی محصولات (وضعیت اکتبر ۲۰۲۶)

• WSO2 API Manager: پلتفرم کامل مدیریت چرخه‌ی عمر API؛ آخرین نسخه‌ی آن 4.7.0 است که در ۲۹ آوریل ۲۰۲۶ منتشر شد و به JDK 21 یا 25 نیاز دارد. در کنار آن «API Platform Gateway» مبتنی بر Envoy (نسخه‌ی 1.2.0 در اوت ۲۰۲۶) و WSO2 Kubernetes Gateway هم عرضه می‌شوند.
• WSO2 Identity Server: محصول متن‌باز مدیریت هویت و دسترسی (IAM/CIAM) با پشتیبانی از OAuth 2.0، OpenID Connect، SAML، احراز هویت چندمرحله‌ای و فدراسیون هویت. آخرین نسخه‌ی آن 7.3.0 است (۱۲ مه ۲۰۲۶).
• WSO2 Integrator: خانواده‌ی محصولات یکپارچه‌سازی که Micro Integrator (اکنون با نام WSO2 Integrator: MI) شناخته‌شده‌ترین عضو آن است. نسخه‌ی MI 4.6.0 و WSO2 Integrator 5.0.0 در ۱۹ مه ۲۰۲۶ منتشر شدند.
• سرویس‌های SaaS: Asgardeo (هویت به‌عنوان سرویس، هم‌کد با Identity Server)، Bijira (مدیریت API ابری که از ۲۰۲۵ جایگزین Choreo for API Management شد)، Devant (یکپارچه‌سازی ابری) و WSO2 Developer Platform (نام جدید Choreo؛ پلتفرم توسعه‌دهندگان داخلی). نسخه‌ی متن‌باز این پلتفرم با نام OpenChoreo اکنون پروژه‌ای در CNCF است.

مدل مجوز و به‌روزرسانی

یکی از نکاتی که اغلب سوءتفاهم ایجاد می‌کند، تفاوت «نسخه‌ی متن‌باز» و «توزیع تجاری» است. کد منبع و نسخه‌های عمومی (GA) که روی GitHub منتشر می‌شوند تحت Apache 2.0 هستند و استفاده از آن‌ها، حتی در محیط عملیاتی، رایگان است. اما توزیعی که از wso2.com دانلود می‌شود تحت WSO2 Software License (EULA) است و به‌روزرسانی‌های امنیتی و رفع اشکال‌ها از طریق ابزار WSO2 Update 2.0 فقط برای مشترکان در دسترس است. کاربران نسخه‌ی متن‌باز این اصلاحات را در نسخه‌ی عمومی بعدی دریافت می‌کنند. طبق سیاست فعلی، هر نسخه دست‌کم سه سال پشتیبانی دارد و برای «خطوط انتشار» که از مارس ۲۰۲۴ معرفی شده‌اند (مثل APIM-4.x و IS-7.x)، دست‌کم هفت سال پشتیبانی در نظر گرفته شده است.

معماری WSO2 API Manager

API Manager از چند جزء منطقی تشکیل شده است که در حالت پیش‌فرض همه در یک فرایند جاوا (All-in-one) اجرا می‌شوند، اما در محیط‌های بزرگ می‌توان آن‌ها را از هم جدا کرد:

• Publisher: پرتال سازندگان API. طراحی API (REST، GraphQL، WebSocket، AsyncAPI و SOAP)، تعریف سیاست‌ها، نسخه‌گذاری، مستندسازی، مدیریت چرخه‌ی عمر (Created، Published، Deprecated و…) و ساخت Revision در این بخش انجام می‌شود.
• Developer Portal: فروشگاه API برای مصرف‌کنندگان. توسعه‌دهندگان در آن API‌ها را جست‌وجو و امتحان می‌کنند، اپلیکیشن می‌سازند، مشترک (Subscribe) می‌شوند و کلید یا توکن دریافت می‌کنند.
• Gateway: قلب مسیر داده. همه‌ی درخواست‌های API از Gateway عبور می‌کنند و احراز هویت، اعمال محدودیت نرخ، تبدیل پیام، مسیریابی و جمع‌آوری داده‌ی تحلیلی در همین‌جا انجام می‌شود. در نسخه‌ی 4.7 علاوه بر Gateway کلاسیک (Synapse)، می‌توان API‌ها را روی API Platform Gateway مبتنی بر Envoy هم مستقر کرد.
• Key Manager: صدور و اعتبارسنجی توکن‌های OAuth 2.0 و کلیدهای API. می‌توان به‌جای Key Manager داخلی از سرویس‌های خارجی مثل WSO2 Identity Server، Keycloak، Okta یا Asgardeo استفاده کرد.
• Traffic Manager: موتور تصمیم‌گیری محدودیت نرخ (Throttling) که رویدادهای Gateway را پردازش می‌کند و سیاست‌هایی مثل «۱۰۰ درخواست در دقیقه برای هر اپلیکیشن» را در کل خوشه اعمال می‌کند.
• Admin Portal: مدیریت سیاست‌های محدودیت، Key Managerها، گردش‌کارهای تأیید، دسته‌بندی API‌ها و تنظیمات سراسری.

WSO2 این اجزا را در قالب چند توزیع جداگانه هم ارائه می‌کند: API Control Plane (شامل Publisher، Developer Portal، Admin و Key Manager)، Universal Gateway و Traffic Manager. تصاویر Docker هرکدام هم جداگانه منتشر می‌شوند (wso2/wso2am-acp، wso2/wso2am-universal-gw و wso2/wso2am-tm).

پورت‌های مهم

کاربردهای رایج WSO2

• انتشار امن API‌های سازمانی: قرار دادن سیستم‌های قدیمی و جدید پشت یک Gateway واحد با احراز هویت OAuth 2.0، محدودیت نرخ و گزارش‌گیری.
• بانکداری باز و فین‌تک: WSO2 «شتاب‌دهنده‌ی خدمات مالی» (Open Banking Accelerator) را روی API Manager و Identity Server ارائه می‌کند.
• API‌های B2B و شرکا: Developer Portal چندمستأجری، گردش‌کار تأیید اشتراک و امکان کسب درآمد (Monetization).
• معماری میکروسرویس: Gateway در نقش لبه‌ی شبکه و مدیریت مرکزی سیاست‌ها روی چند Gateway، حتی Gatewayهای دیگر مثل AWS، Azure یا Kong (Federated Gateways).
• AI Gateway و MCP: نسخه‌های اخیر امکاناتی برای مدیریت API‌های مدل‌های زبانی، Guardrailها، مسیریابی هوشمند بین مدل‌ها و حاکمیت بر سرورهای MCP اضافه کرده‌اند.
• ورود یکپارچه و CIAM: با Identity Server یا Asgardeo؛ و یکپارچه‌سازی سیستم‌ها با Micro Integrator برای تبدیل پیام، اتصال به پایگاه‌داده، صف‌ها و سرویس‌های SOAP.

نصب سریع WSO2 API Manager با Docker

WSO2 تصاویر رسمی را روی Docker Hub با نام wso2/wso2am منتشر می‌کند. برای نسخه‌ی 4.7.0 سه گونه وجود دارد: 4.7.0 (پایه‌ی Ubuntu)، 4.7.0-alpine و 4.7.0-rocky. این تصاویر با کاربر غیرریشه‌ی wso2carbon (شناسه‌ی 10001) اجرا می‌شوند و محصول در مسیر /home/wso2carbon/wso2am-4.7.0 نصب شده است. برای آزمایش سریع کافی است:

docker run -d --name apim \
  -p 9443:9443 -p 8243:8243 -p 8280:8280 \
  wso2/wso2am:4.7.0

# follow the log until the server reports it has started
docker logs -f apim

راه‌اندازی اولیه بسته به سخت‌افزار یک تا چند دقیقه طول می‌کشد. سپس این نشانی‌ها در دسترس‌اند (نام کاربری و رمز پیش‌فرض admin / admin است و مرورگر به‌خاطر گواهی خودامضا هشدار می‌دهد):

• https://localhost:9443/publisher — پرتال Publisher
• https://localhost:9443/devportal — پرتال توسعه‌دهندگان
• https://localhost:9443/admin — پرتال مدیریت
• https://localhost:8243/ — نقطه‌ی فراخوانی API‌ها از طریق Gateway

این حالت فقط برای آشنایی و آزمایش مناسب است: داده‌ها در پایگاه‌داده‌ی جاسازی‌شده‌ی H2 و داخل خود کانتینر ذخیره می‌شوند و با حذف کانتینر از بین می‌روند. همچنین حافظه‌ی پیش‌فرض JVM برابر -Xms256m -Xmx1024m است که برای بار واقعی کافی نیست.

استقرار با Docker Compose و پایگاه‌داده‌ی MySQL

برای یک محیط پایدار، پایگاه‌داده را بیرون از API Manager نگه می‌داریم. API Manager دو پایگاه‌داده‌ی اصلی دارد: apim_db (داده‌های API‌ها، اپلیکیشن‌ها، اشتراک‌ها و توکن‌ها) و shared_db (کاربران، نقش‌ها و رجیستری). ساختار پوشه‌ی پروژه به این شکل است:

wso2-apim/
├── .env
├── docker-compose.yml
├── apim/
│   └── Dockerfile
├── mysql-init/
│   ├── 01-databases.sql
│   ├── 02-shared.sql
│   └── 03-apim.sql
└── wso2-config/
    └── repository/
        ├── conf/deployment.toml
        └── resources/security/   # keystores / truststore (optional)

تصویر رسمی درایور JDBC مربوط به MySQL را ندارد؛ بنابراین یک Dockerfile کوچک می‌نویسیم که درایور را به پوشه‌ی repository/components/lib اضافه کند (طبق مستندات، نسخه‌ی Connector/J 8.4 با MySQL 8.4 سازگار است):

# apim/Dockerfile
FROM wso2/wso2am:4.7.0
ARG MYSQL_CONNECTOR_VERSION=8.4.0
ADD --chown=wso2carbon:wso2 \
  https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/${MYSQL_CONNECTOR_VERSION}/mysql-connector-j-${MYSQL_CONNECTOR_VERSION}.jar \
  ${WSO2_SERVER_HOME}/repository/components/lib/

API Manager به collation حساس به حروف بزرگ و کوچک نیاز دارد؛ collation پیش‌فرض MySQL 8 یعنی utf8mb4_0900_ai_ci نباید استفاده شود. اسکریپت اول، پایگاه‌داده‌ها و کاربر را می‌سازد:

-- mysql-init/01-databases.sql
CREATE DATABASE apim_db   CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
CREATE DATABASE shared_db CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
CREATE USER 'apimuser'@'%' IDENTIFIED BY 'Str0ng-DB-Passw0rd';
GRANT ALL PRIVILEGES ON apim_db.*   TO 'apimuser'@'%';
GRANT ALL PRIVILEGES ON shared_db.* TO 'apimuser'@'%';
FLUSH PRIVILEGES;

اسکریپت‌های ساخت جدول‌ها داخل خود توزیع وجود دارند (dbscripts/mysql.sql برای shared_db و dbscripts/apimgt/mysql.sql برای apim_db). آن‌ها را مستقیم از تصویر استخراج می‌کنیم تا دقیقاً با نسخه‌ی نصب‌شده هم‌خوان باشند:

IMG=wso2/wso2am:4.7.0
HOME_DIR=/home/wso2carbon/wso2am-4.7.0

{ echo "USE shared_db;"; docker run --rm --entrypoint cat $IMG $HOME_DIR/dbscripts/mysql.sql; } \
  > mysql-init/02-shared.sql
{ echo "USE apim_db;";   docker run --rm --entrypoint cat $IMG $HOME_DIR/dbscripts/apimgt/mysql.sql; } \
  > mysql-init/03-apim.sql

حالا فایل Compose را می‌نویسیم. نکته‌ی مهم این است که تصویر رسمی هنگام شروع، محتوای پوشه‌ی /home/wso2carbon/wso2-config-volume را روی پوشه‌ی نصب محصول کپی می‌کند؛ پس کافی است deployment.toml و فایل‌های امنیتی را با همان ساختار پوشه‌ها در این مسیر Mount کنیم:

# docker-compose.yml
services:
  mysql:
    image: mysql:8.4
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    volumes:
      - mysql-data:/var/lib/mysql
      - ./mysql-init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p$$MYSQL_ROOT_PASSWORD --silent"]
      interval: 15s
      timeout: 10s
      retries: 10
      start_period: 60s

  apim:
    build: ./apim
    image: local/wso2am-mysql:4.7.0
    restart: unless-stopped
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      JVM_MEM_OPTS: "-Xms1g -Xmx2g"
    ports:
      - "9443:9443"
      - "8243:8243"
      - "8280:8280"
    volumes:
      - ./wso2-config:/home/wso2carbon/wso2-config-volume:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9763/services/Version"]
      interval: 15s
      timeout: 5s
      retries: 20
      start_period: 180s

volumes:
  mysql-data:

# .env  (keep this file out of Git)
MYSQL_ROOT_PASSWORD=Ch4nge-Me-Root

فایل‌های داخل wso2-config باید برای کاربر کانتینر (UID 10001) قابل‌خواندن باشند (مثلاً chmod -R o+rX wso2-config). با docker compose up -d --build همه‌چیز بالا می‌آید؛ در اولین اجرا MySQL اسکریپت‌ها را اجرا می‌کند و API Manager فقط پس از سالم شدن پایگاه‌داده شروع می‌شود. متغیر JVM_MEM_OPTS را اسکریپت راه‌انداز api-manager.sh می‌خواند و جایگزین مقدار پیش‌فرض حافظه می‌کند.

تنظیمات کلیدی deployment.toml

از نسخه‌ی 3 به بعد، تقریباً همه‌ی تنظیمات WSO2 در یک فایل TOML متمرکز شده‌اند و سرور هنگام شروع، فایل‌های XML داخلی را از روی آن می‌سازد. یک نمونه‌ی حداقلی برای سناریوی بالا:

[server]
hostname = "apim.example.com"
base_path = "${carbon.protocol}://${carbon.host}:${carbon.management.port}"
server_role = "default"

[super_admin]
username = "admin"
password = "$secret{admin_password}"
create_admin_account = true

[user_store]
type = "database_unique_id"

[database.apim_db]
type = "mysql"
url = "jdbc:mysql://mysql:3306/apim_db?useSSL=false&allowPublicKeyRetrieval=true"
username = "apimuser"
password = "$secret{db_password}"
driver = "com.mysql.cj.jdbc.Driver"
pool_options.maxActive = 100
pool_options.maxWait = 10000

[database.shared_db]
type = "mysql"
url = "jdbc:mysql://mysql:3306/shared_db?useSSL=false&allowPublicKeyRetrieval=true"
username = "apimuser"
password = "$secret{db_password}"
driver = "com.mysql.cj.jdbc.Driver"

[transport.https.properties]
proxyPort = 443

[[apim.gateway.environment]]
name = "Default"
type = "hybrid"
gateway_type = "Regular"
provider = "wso2"
display_in_api_console = true
service_url = "https://localhost:${mgt.transport.https.port}/services/"
username = "${admin.username}"
password = "${admin.password}"
http_endpoint = "http://gw.example.com"
https_endpoint = "https://gw.example.com"
# WebSocket APIs use ports 9099/8099; publish them separately if needed
ws_endpoint = "ws://gw.example.com:9099"
wss_endpoint = "wss://gw.example.com:8099"

[apim.devportal]
url = "https://apim.example.com/devportal"

[encryption]
key = "<64-character-hex-key>"

[secrets]
admin_password = "[Your-Strong-Admin-Password]"
db_password = "[Str0ng-DB-Passw0rd]"

توضیح بخش‌های مهم:

• [server] hostname: نام دامنه‌ای که کاربران با آن به پرتال‌ها می‌رسند. اگر این مقدار localhost بماند، Redirectهای ورود (OIDC) کاربران را به localhost می‌فرستند.
• [database.*]: چون این مقادیر داخل فایل‌های XML قرار می‌گیرند، کاراکتر & در URL باید به‌صورت & نوشته شود. در Production به‌جای useSSL=false اتصال TLS به پایگاه‌داده را فعال کنید و پایگاه‌داده را روی منطقه‌ی زمانی UTC نگه دارید.
• [user_store]: نوع پیش‌فرض database_unique_id کاربران را در shared_db نگه می‌دارد؛ برای اتصال به LDAP یا Active Directory می‌توان نوع آن را به read_only_ldap_unique_id یا active_directory_unique_id تغییر داد و مشخصات اتصال را افزود.
• [[apim.gateway.environment]]: نشانی‌هایی که در Developer Portal به‌عنوان Endpoint نمایش داده می‌شوند. وقتی Gateway پشت Nginx است، باید نشانی عمومی را اینجا بنویسید.
• [encryption] key: از نسخه‌ی 4.7 رمزنگاری پیش‌فرض داده‌های حساس از RSA به رمزنگاری متقارن AES-GCM تغییر کرده است. یک کلید ۶۴ کاراکتری هگز (مثلاً با openssl rand -hex 32) بسازید، از آن نسخه‌ی پشتیبان امن بگیرید و در همه‌ی گره‌های خوشه یکسان نگه دارید؛ گم‌شدن این کلید یعنی ازدست‌رفتن داده‌های رمزشده.
• حافظه‌ی JVM: در Docker با متغیر JVM_MEM_OPTS و در نصب معمولی با ویرایش همان متغیر در bin/api-manager.sh تنظیم می‌شود. سقف Heap را حدود نیمی تا دو سوم حافظه‌ی کانتینر در نظر بگیرید تا برای Metaspace و بافرهای شبکه جا بماند.

بخش [secrets] با ابزار Cipher Tool رمز می‌شود. مقدارهای داخل کروشه، رمزهای خام هستند و پس از اجرای دستور زیر در پوشه‌ی محصول با متن رمزشده جایگزین می‌شوند و در بقیه‌ی فایل با $secret{...} به آن‌ها ارجاع می‌دهیم:

cd /home/wso2carbon/wso2am-4.7.0
./bin/ciphertool.sh -Dconfigure

در Docker، این دستور را یک بار روی نسخه‌ای از توزیع اجرا کنید و فایل TOML حاصل را در wso2-config قرار دهید؛ یا رمزها را از یک سامانه‌ی مدیریت اسرار (مثل Kubernetes Secret یا Vault) تأمین کنید. توجه کنید که [super_admin] فقط در اولین راه‌اندازی، حساب مدیر را در پایگاه‌داده می‌سازد؛ تغییر رمز بعدی باید از کنسول مدیریت (/carbon) انجام شود.

پیکربندی SSL/TLS

API Manager به‌صورت پیش‌فرض با keystore خودامضای wso2carbon.jks (در مسیر repository/resources/security، با رمز wso2carbon) عرضه می‌شود. این کلید خصوصی در همه‌ی نصب‌های دنیا یکسان است؛ بنابراین در هیچ محیط واقعی نباید بدون تغییر باقی بماند. دو راه اصلی داریم: خاتمه‌دادن TLS روی Nginx (پیشنهادی) یا نصب مستقیم گواهی معتبر روی خود WSO2. در بسیاری از محیط‌ها هر دو را با هم انجام می‌دهند.

ساخت keystore از گواهی Let's Encrypt

فرض کنید با certbot گواهی دامنه‌های apim.example.com و gw.example.com را گرفته‌اید (هر دو در SAN یک گواهی). ابتدا کلید و زنجیره‌ی گواهی را به PKCS12 و سپس به JKS تبدیل می‌کنیم. WSO2 الزام می‌کند رمز keystore و رمز کلید خصوصی یکسان باشند:

LE=/etc/letsencrypt/live/apim.example.com
KS_PASS='Str0ng-Keystore-Pass'

openssl pkcs12 -export \
  -in  $LE/fullchain.pem \
  -inkey $LE/privkey.pem \
  -name apimcert \
  -out apim.p12 -passout pass:$KS_PASS

keytool -importkeystore \
  -srckeystore apim.p12 -srcstoretype PKCS12 -srcstorepass "$KS_PASS" \
  -destkeystore apim-tls.jks -deststoretype JKS -deststorepass "$KS_PASS" \
  -alias apimcert

سپس گواهی عمومی را در truststore پیش‌فرض (client-truststore.jks با رمز پیش‌فرض wso2carbon) وارد می‌کنیم تا ارتباط داخلی اجزا با نام دامنه‌ی جدید معتبر شناخته شود:

keytool -export -alias apimcert -keystore apim-tls.jks \
  -storepass "$KS_PASS" -file apimcert.crt

keytool -import -noprompt -alias apimcert -file apimcert.crt \
  -keystore client-truststore.jks -storepass wso2carbon

هر دو فایل را در wso2-config/repository/resources/security/ قرار دهید (نسخه‌ای کامل از client-truststore.jks اصلی که گواهی جدید به آن اضافه شده) و در TOML معرفی کنید:

[keystore.tls]
file_name = "apim-tls.jks"
type = "JKS"
password = "Str0ng-Keystore-Pass"
alias = "apimcert"
key_password = "Str0ng-Keystore-Pass"

[truststore]
file_name = "client-truststore.jks"
type = "JKS"
password = "wso2carbon"

بخش [keystore.tls] فقط گواهی ارتباطات HTTPS را عوض می‌کند. keystore اصلی ([keystore.primary]) برای امضای توکن‌ها و کارهای داخلی استفاده می‌شود و تغییر آن روی سیستمی که داده دارد باید با برنامه‌ریزی انجام شود. گواهی Let's Encrypt هر ۹۰ روز تمدید می‌شود؛ تبدیل بالا را در یک اسکریپت پس از تمدید (deploy hook) خودکار کنید. به همین دلیل ساده‌تر است که گواهی عمومی فقط روی Nginx باشد.

Nginx به‌عنوان Reverse Proxy با خاتمه‌ی TLS

در این الگو کاربران فقط با پورت 443 کار می‌کنند و Nginx درخواست‌ها را به پورت‌های 9443 و 8243 کانتینر می‌فرستد. پیکربندی زیر برگرفته از الگوی مستندات WSO2 است:

upstream apim_mgmt { server 127.0.0.1:9443; }
upstream apim_gw   { server 127.0.0.1:8243; }

server {
    listen 80;
    server_name apim.example.com gw.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name apim.example.com;

    ssl_certificate     /etc/letsencrypt/live/apim.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/apim.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Port  443;
        proxy_read_timeout 5m;
        proxy_send_timeout 5m;
        proxy_pass https://apim_mgmt;
    }
}

server {
    listen 443 ssl;
    http2 on;
    server_name gw.example.com;

    ssl_certificate     /etc/letsencrypt/live/apim.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/apim.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    client_max_body_size 20m;

    location / {
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_pass https://apim_gw;
    }
}

دستور http2 on; در Nginx 1.25.1 و بالاتر پشتیبانی می‌شود؛ در نسخه‌های قدیمی‌تر به‌جای آن listen 443 ssl http2; بنویسید. پس از این کار، در TOML همان‌طور که دیدیم hostname را برابر دامنه‌ی عمومی و proxyPort را 443 بگذارید. اگر پرتال‌ها با چند نام دامنه در دسترس هستند، گزینه‌ی customUrl را در فایل‌های settings.json مربوط به Publisher، Developer Portal و Admin فعال کنید تا Callback ورود بر اساس سرآیند X-Forwarded-Host ساخته شود. در این حالت پورت‌های 9443 و 8243 را فقط روی شبکه‌ی داخلی یا 127.0.0.1 باز نگه دارید.

استقرار در محیط Production

پایگاه‌داده و پایداری داده‌ها

H2 فقط برای آزمایش است. در Production از MySQL، PostgreSQL، Oracle یا SQL Server پشتیبانی‌شده استفاده کنید، خود پایگاه‌داده را هم به‌صورت HA (Replication یا سرویس مدیریت‌شده‌ی ابری) راه‌اندازی کنید و تنظیمات Pool اتصال را با بار واقعی هماهنگ کنید. مستندات WSO2 برای خوشه‌های MySQL پیکربندی Failover را به Load Balanced ترجیح می‌دهد.

خوشه‌بندی و جداسازی اجزا

• Active-Active با دو گره All-in-one: ساده‌ترین الگوی HA. هر دو گره به پایگاه‌داده‌های مشترک وصل‌اند و پشت یک Load Balancer قرار می‌گیرند. چون کنسول مدیریت به Session وابسته است، Load Balancer باید Sticky Session (مثلاً ip_hash) داشته باشد.
• استقرار توزیع‌شده: Control Plane، Gateway و Traffic Manager روی گره‌های جدا. Gatewayها مستقل از پرتال‌ها مقیاس‌پذیر می‌شوند و می‌توان Gateway جداگانه‌ای برای ترافیک داخلی و خارجی (یا Production و Sandbox) داشت. در نسخه‌های 4.x، Gatewayها مصنوعات API را از Control Plane همگام‌سازی می‌کنند و نیازی به فایل‌سیستم مشترک برای API‌ها نیست.
• Kubernetes و Helm: مخزن رسمی wso2/helm-apim چارت‌های All-in-one و توزیع‌شده (Control Plane، Gateway و Traffic Manager) را برای نسخه‌ی 4.7.0 نگه‌داری می‌کند. همچنین WSO2 Kubernetes Gateway و API Platform Gateway برای معماری‌های Kubernetes-native در دسترس‌اند.

سخت‌سازی امنیتی (Hardening)

• رمز admin را پیش از اولین راه‌اندازی عوض کنید، حساب‌های جداگانه با نقش‌های محدود (مثلاً فقط Publisher یا فقط Subscriber) بسازید و از حساب super admin برای کار روزمره استفاده نکنید.
• keystore و truststore پیش‌فرض را جایگزین کنید و همه‌ی رمزهای پیش‌فرض (wso2carbon) را تغییر دهید.
• همه‌ی رمزهای موجود در TOML را با Secure Vault و Cipher Tool رمز کنید.
• کنسول /carbon و پرتال‌های Publisher و Admin را فقط از شبکه‌ی داخلی یا VPN در دسترس بگذارید و فقط Gateway و در صورت نیاز Developer Portal را عمومی کنید.
• پورت‌های داخلی (9763، 5672، 9611، 9711) را با فایروال ببندید.
• از سیاست پیش‌فرض «منع دسترسی» در 4.7 برای مسیرهای Control Plane استفاده کنید و فقط مسیرهای لازم را با [[resource.access_control]] باز کنید.
• به‌روزرسانی‌های امنیتی را دنبال کنید: مشترکان با WSO2 Update 2.0 و کاربران نسخه‌ی متن‌باز با ارتقا به آخرین نسخه‌ی عمومی؛ اطلاعیه‌های امنیتی در security.docs.wso2.com منتشر می‌شوند.

لاگ، پایش و پشتیبان‌گیری

لاگ‌های اصلی در repository/logs قرار دارند: wso2carbon.log (لاگ سرور)، http_access_*.log (دسترسی‌ها) و audit.log (اقدامات مدیریتی). پیکربندی لاگ در repository/conf/log4j2.properties است. در محیط کانتینری، لاگ‌ها را به stdout یا یک جمع‌کننده‌ی مرکزی (ELK، Loki و…) بفرستید. برای پایش، JMX و متریک‌های JVM، سلامت Endpoint /services/Version و زمان پاسخ Gateway را زیر نظر بگیرید. داده‌های تحلیلی API را هم می‌توان به سرویس‌هایی مثل Moesif یا پشته‌ی ELK فرستاد. برنامه‌ی پشتیبان‌گیری باید شامل پایگاه‌داده‌ها، deployment.toml، keystoreها و کلید رمزنگاری [encryption] باشد؛ و بازیابی آن را دوره‌ای در محیط تست تمرین کنید.

مقایسه‌ی WSO2 با محصولات مشابه

در حوزه‌ی مدیریت هویت هم مقایسه‌ی رایج، WSO2 Identity Server با Keycloak است:

به‌طور خلاصه، اگر یک پلتفرم کامل و خودمیزبان با Developer Portal، Key Manager و سیاست‌های سازمانی می‌خواهید و نمی‌خواهید به یک ارائه‌دهنده‌ی ابری وابسته شوید، WSO2 گزینه‌ی بسیار جدی است. اگر فقط یک Gateway سبک لازم دارید، Kong یا Tyk ساده‌ترند و اگر کاملاً روی یک ابر خاص هستید، سرویس مدیریت‌شده‌ی همان ابر هزینه‌ی نگه‌داری کمتری دارد.

رفع اشکال‌های رایج

• کانتینر پس از چند دقیقه متوقف می‌شود یا خطای OutOfMemoryError می‌دهد: JVM_MEM_OPTS و محدودیت حافظه‌ی کانتینر را هماهنگ کنید و با docker logs و docker inspect (وضعیت OOMKilled) علت را بررسی کنید.
• Communications link failure یا Access denied هنگام اتصال به MySQL: مطمئن شوید API Manager پس از سالم شدن MySQL شروع می‌شود (healthcheck)، درایور در components/lib قرار دارد، & در URL رعایت شده و کاربر اجازه‌ی اتصال از '%' را دارد.
• خطای PKIX path building failed: گواهی سرور مقصد در client-truststore.jks نیست؛ آن را با keytool -import اضافه و سرور را راه‌اندازی مجدد کنید.
• انتقال به localhost پس از ورود یا خطای «Registered callback does not match»: مقدار hostname و proxyPort را بررسی و در صورت نیاز customUrl را فعال کنید.
• خطای 403 روی مسیرهای سفارشی پس از ارتقا به 4.7: نتیجه‌ی سیاست جدید منع پیش‌فرض است؛ مسیر را با [[resource.access_control]] مجاز کنید.
• عدم اعتبار توکن‌ها یا خطاهای زمانی: ساعت همه‌ی گره‌ها را با NTP همگام کنید و پایگاه‌داده را روی UTC نگه دارید.
• داده‌های تکراری یا رفتار عجیب در جست‌وجو و کلیدها: collation پایگاه‌داده را بررسی کنید؛ باید حساس به حروف (مثل utf8mb4_bin) باشد.
• مشکل در پورت 9443: اگر پورت در میزبان اشغال است (مثلاً در Rancher)، با [server] offset همه‌ی پورت‌ها را جابه‌جا کنید؛ با offset=1 پورت‌ها 9444 و 8244 می‌شوند.

جمع‌بندی

WSO2 یکی از معدود پلتفرم‌هایی است که مدیریت API، هویت و یکپارچه‌سازی را با کد متن‌باز و امکان استقرار کاملاً خودمیزبان کنار هم ارائه می‌کند. WSO2 API Manager 4.7 با Gateway جدید مبتنی بر Envoy، رمزنگاری متقارن پیش‌فرض، کلیدهای API وابسته به API و امکانات حاکمیت بر MCP نشان می‌دهد که محصول به‌سمت معماری‌های Cloud-native و هوش مصنوعی حرکت می‌کند. راه‌اندازی آزمایشی با Docker چند دقیقه طول می‌کشد، اما رسیدن به یک محیط Production قابل‌اعتماد به پایگاه‌داده‌ی خارجی، گواهی معتبر، Reverse Proxy، رمزنگاری اسرار، پایش و پشتیبان‌گیری منظم نیاز دارد. اگر این گام‌ها را با دقت بردارید، یک پلتفرم API سازمانی و مستقل از ارائه‌دهنده‌ی ابری در اختیار خواهید داشت.

منابع

• WSO2 — وب‌سایت رسمی
• WSO2 Support Matrix — تاریخ انتشار و پشتیبانی نسخه‌ها
• About this Release — WSO2 API Manager 4.7.0 Documentation
• WSO2 API Manager 4.7.0 Release — GitHub
• What's New in WSO2 API Manager 4.7 — WSO2 Blog
• WSO2 Identity Server — Versions (7.3.0)
• wso2/wso2am — Docker Hub
• wso2/docker-apim — Docker and Docker Compose resources
• wso2/helm-apim — Helm charts for WSO2 API Manager
• Changing to MySQL — WSO2 API Manager Documentation
• Creating New Keystores — WSO2 API Manager Documentation
• Configuring the Proxy Server and the Load Balancer — WSO2 API Manager Documentation
• WSO2 Subscriptions: Service Definition and FAQ
• EQT Completes Acquisition of WSO2 (August 2024)
• New WSO2 API Management Offerings (Bijira, March 2025)
• OpenChoreo — CNCF