Before building the frontend, backend, or mobile components, ensure your local environment meets the following requirements:

• Frontend: Node.js version 18 or higher. Run node -v in your terminal to verify. Use nvm (Node Version Manager) if you need to switch between versions.
• Backend: Java (JDK 8 or JDK 17), MySQL 5.7 or higher, and Redis.

Clone Repository & Execute SQL

1. Download the source code from the official repository: [gitee.com/lab1024/smart-admin](https://gitee.com/lab1024/smart-admin)

   • Backend: Use smart-admin-api-java8-springboot2 for Java 8 + Spring Boot 2.x, or smart-admin-api-java17-springboot3 for Java 17 + Spring Boot 3.x.
   • Frontend: Use smart-admin-web-javascript (JS version) or smart-admin-web-typescript (TS version).
   • Mobile (H5, mini-program, app): Use smart-app (uniapp JS version).
   • SQL script: Located at /sql/smart_admin_v3.sql.

2. Execute the SQL script: Run /sql/smart_admin_v3.sql in your database management tool. Once successfully executed, a database named smart_admin_v3 will be created.

Start Redis

If you already have a Redis instance running, you may skip this step. Otherwise, install it via:

• Linux: redis.io/download
• Windows: github.com/microsoftarchive/redis/releases

Import Backend Project & Update Configuration

1. Import the backend: Load either smart-admin-api-java8-springboot2 or smart-admin-api-java17-springboot3 into IntelliJ IDEA or Eclipse as a Maven project. Ensure your IDE's file encoding is set to UTF-8.

2. Configure YAML files: The configuration files contain Chinese comments; verify your IDE encoding to ensure they display correctly.

   • Edit sa-base/src/main/resources/dev/sa-base.yaml:

     • JDBC Parameters:

       spring:
         datasource:
           url: jdbc:p6spy:mysql://127.0.0.1:3306/smart_admin_v3?autoReconnect=true&useServerPreparedStmts=false&rewriteBatchedStatements=true&characterEncoding=UTF-8&useSSL=false&allowMultiQueries=true&serverTimezone=Asia/Shanghai
           username: root
           password: YourPasswordHere
       

     • Redis Parameters:

       redis:
         database: 1
         host: 127.0.0.1
         port: 6379
         password:
         timeout: 10000ms
         lettuce:
           pool:
             max-active: 5
             min-idle: 1
             max-idle: 3
             max-wait: 30000ms
       

     • File Upload Configuration (Default Local Storage):

       file:
         storage:
           mode: local
           local:
             upload-path: /home/smart_admin_v3/upload/
             url-prefix:
           cloud:
             region: oss-cn-qingdao
             endpoint: oss-cn-qingdao.aliyuncs.com
             bucket-name: common
             access-key:
             secret-key:
             url-prefix: https://${file.storage.cloud.bucket-name}.${file.storage.cloud.endpoint}/
             private-url-expire-seconds: 3600
       

   • Edit sa-admin/src/main/resources/dev/application.yaml:

     • Log Directory (for log4j2 and Tomcat logs):

       project:
         name: sa-admin
         log-directory: /home/smart-admin/${project.name}/${spring.profiles.active}
       

     • Server Port:

       server:
         port: 1024
         servlet:
           context-path: /
       

Launch Backend

Locate the AdminApplication class within the sa-admin module and run it. Navigate to http://localhost:1024/swagger-ui/index.html to access the Swagger documentation. Login Credentials: API account: api, password: 1024. Your backend is now operational.

Launch Frontend

1. Select a version: Choose between JS or TS (the JS version is recommended by the author).

   • JS: Navigate to the smart-admin-web-javascript directory.
   • TS: Navigate to the smart-admin-web-typescript directory.

2. Install dependencies: Run npm install.

3. Start the development server: Run npm run dev.

4. Access the application: Visit http://localhost:8080 and log in with the credentials admin / 123456.

Launch Mobile (H5 / Mini-program / App)

1. Navigate to the smart-app directory.
2. Run npm install to install the required packages.
3. Run npm run dev:h5 to launch the H5 development environment.
4. Visit http://localhost:8080 and log in with admin / 123456.
5. For mini-programs or native apps, refer to the specific uniapp documentation for the appropriate build commands.

Project Architecture: Three Key Terms

The project structure is organized around three core concepts: business, system, and support.

• business: Contains domain-specific logic. For example, in an ERP inventory system, this layer handles product management, warehouse operations, and inbound/outbound logistics.
• system: Manages core system functionalities, including employee records, department structures, roles, permissions, and menu configurations.
• support: Provides essential infrastructure required by every system without containing specific business logic. This includes configuration parameters, data dictionaries, file handling, caching, heartbeat monitoring, and various logs (login, data changes, etc.).

Nginx Configuration Examples

HTTPS Configuration

server {
    listen 80;
    listen 443 ssl;
    server_name  preview.smartadmin.vip;

    ssl_certificate /home/ssl/smartadmin.vip/smartadmin.vip.pem;
    ssl_certificate_key /home/ssl/smartadmin.vip/smartadmin.vip.key;
    ssl_session_timeout 5m;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    gzip on;
    gzip_min_length 1k;
    gzip_buffers 4 16k;
    gzip_comp_level 3;
    gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/x-httpd-php image/jpeg image/gif image/png;
    gzip_vary on;
    gzip_disable "MSIE [1-6]\.";

    if ($request_method ~* OPTIONS) {
        return 403;
    }

    location / {
        alias /home/smart-admin-v3-preview/dist/;
        try_files $uri $uri/ /index.html last;
        index  index.html;
        expires -1;
    }

    location /smart-admin-api/ {
        proxy_pass  http://127.0.0.1:1024/smart-admin-api/;
        proxy_redirect    off;
        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_set_header  Host $http_host;
        expires -1;
        add_header Set-Cookie "Path=/; HttpOnly; Secure";
        add_header X-Content-Type-Options "nosniff";
        add_header X-XSS-Protection "1; mode=block";
        add_header X-Frame-Options "ALLOW-FROM preview.smartadmin.vip";
        add_header Content-Security-Policy "frame-ancestors preview.smartadmin.vip";
    }

    location /v3/api-docs/ {
        proxy_pass  http://127.0.0.1:1024/smart-admin-api/v3/api-docs/;
        proxy_redirect    off;
        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_set_header  Host $http_host;
        add_header X-Frame-Options "ALLOW-FROM preview.smartadmin.vip";
        add_header Content-Security-Policy "frame-ancestors preview.smartadmin.vip";
        expires -1;
    }
}

HTTP Configuration

server {
    listen 80;
    listen [::]:80;
    server_name api.xxx.com;
    access_log /www/wwwlogs/api.xxx.com.log combined;
    error_log /www/wwwlogs/api.xxx.com.err;
    index index.html index.htm;
    root /www/wwwroot/your-project/smart-web/dist;
    client_body_timeout 60s;
    client_header_timeout 60s;
    client_max_body_size 20m;
    add_header Referrer-Policy 'origin' always;
    add_header Content-Security-Policy "default-src 'self' *.xxx.com data: https: 'unsafe-inline'; frame-ancestors 'self' *.xxx.com" always;
    add_header X-Content-Type-Options "nosniff";
    add_header X-Download-Options noopen;
    add_header X-Frame-Options "ALLOW-FROM *.xxx.com";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Permitted-Cross-Domain-Policies none;
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains";
    add_header Set-Cookie "Path=/; HttpOnly; Secure";
    add_header Access-Control-Allow-Origin '*.xxx.com';
    add_header Access-Control-Allow-Credentials 'true';
    add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
    add_header Access-Control-Allow-Headers 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
    error_page 404 /404.html;
    error_page 502 /502.html;

    location ~ .*\.(wma|wmv|asf|mp3|mmf|zip|rar|swf|flv|mp4)$ {
        valid_referers none blocked *.xxx.com api.xxx.com;
        if ($invalid_referer) {
            return 403;
        }
    }

    location / {
        expires epoch;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_pass http://127.0.0.1:1024/api/;
        proxy_redirect off;
        proxy_buffering off;
        expires -1;
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    location /wechat/xxx.txt {
        default_type text/html;
        return 200 "xxxxx";
    }

    location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ {
        expires 30d;
        access_log off;
    }

    location ~ .*\.(js|css)?$ {
        expires 7d;
        access_log off;
    }

    location ~ /(\.user\.ini|\.ht|\.git|\.svn|\.project|LICENSE|README\.md) {
        deny all;
        return 403;
    }

    location /.well-known {
        allow all;
    }
}