Univer Pro

https://docs.univer.ai/guides/pro
Admin
Univer Pro extends open-source Univer with enterprise-grade features including real-time...
Tokens:21,737
Snippets:234
Trust Score:7.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Configuration Example

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

A comprehensive example for integrating USIP, custom RDS, external S3 storage, and scaling service instances.

```text
# 1. enable USIP integration
# usip about
USIP_ENABLED=true
USIP_URI_CREDENTIAL=https://usip-demo.univer.ai/usip/credential
USIP_URI_USERINFO=https://usip-demo.univer.ai/usip/userinfo
USIP_URI_ROLE=https://usip-demo.univer.ai/usip/role
USIP_URI_COLLABORATORS=https://usip-demo.univer.ai/usip/collaborators
USIP_URI_UNITEDITTIME=https://usip-demo.univer.ai/usip/unit-edit-time

# 2. only owner can copy content and print
AUTH_PERMISSION_CUSTOMER_STRATEGIES=[ {"action": 3, "role": 2}, {"action": 6, "role": 2} ]

# 3. enable univer event sync
EVENT_SYNC=true # Set to true to enable

# 4. use owner RDS
# postgresql config
DISABLE_UNIVER_RDS=true # When using your own RDS, disable Univer's default PostgreSQL

DATABASE_DRIVER=postgresql # Set to postgresql for PostgreSQL-compatible databases
DATABASE_HOST=univer-postgresql
DATABASE_PORT=5432
DATABASE_DBNAME=univer
DATABASE_USERNAME=universer-biz
DATABASE_PASSWORD=123456

# 5. use owner Object storage
# s3 config
DISABLE_UNIVER_S3=true # When using your own object storage, disable Univer's built-in MinIO

S3_USER=universer-biz
S3_PASSWORD=123456
S3_REGION=cn-sz
S3_PATH_STYLE=true
S3_ENDPOINT=univer-s3:9652
S3_ENDPOINT_PUBLIC=univer.ai:9653
S3_DEFAULT_BUCKET=univer

# 6. change univer service Port
HOST_NGINX_PORT=8010

# 7. set the service scale
UNIVERSER_REPLICATION_CNT=4 # universer instance count
COLLABORATION_SERVER_REPLICATION_CNT=5 # collaboration service instance count
MAX_MEMORY_LIMIT=2048 # collaboration service max memory limit, in MB
```

--------------------------------

### Start Docker Compose Services

Source: https://docs.univer.ai/guides/pro/downtime-upgrade

Execute the start script to launch the new version of the services.

```bash
bash run.sh start
```

--------------------------------

### Install Univer Server via Script

Source: https://docs.univer.ai/guides/pro/server

Use these commands to install the latest version or a specific version of the Univer server.

```bash
bash -c "$(curl -fsSL https://get.univer.ai)"
```

```bash
bash -c "$(curl -fsSL https://get.univer.ai/product)" -- 0.9.1
```

--------------------------------

### Configure and Start USIP Demo

Source: https://docs.univer.ai/guides/pro/server

Enable USIP by modifying the environment configuration and restarting the services.

```bash
USIP_ENABLED=true
```

```bash
bash run.sh restart
```

```bash
bash run.sh start-demo-usip
```

--------------------------------

### Deploy Observability Components (Online)

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Install observability components for monitoring Univer services in an online environment.

```bash
helm upgrade --install -n univer-observability --create-namespace \
    --set global.univerNamespace="univer" \
    univer-observability \
    oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-observability
```

--------------------------------

### Verify License Entitlements

Source: https://docs.univer.ai/guides/pro/license

Example JSON response from the server license verification endpoint.

```json
{
  "verify": "true",
  "release_type": "COMMERCIAL"
}
```

--------------------------------

### Deploy Univer Server to Kubernetes

Source: https://docs.univer.ai/guides/pro/server

Use Helm to install the Univer stack and restart the necessary deployments.

```bash
helm install -n univer --create-namespace \
  --set global.istioNamespace="univer" \
  univer-stack oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack
kubectl rollout restart -n univer deployment/collaboration-server
kubectl rollout restart -n univer deployment/universer
```

```bash
helm uninstall univer-stack -n univer
```

--------------------------------

### Upgrade Univer Server

Source: https://docs.univer.ai/guides/pro/server

Run the installer script in the parent directory to upgrade the server while preserving existing configuration and data.

```bash
bash -c "$(curl -fsSL https://get.univer.ai)"
```

--------------------------------

### Deploy Observability Components (Offline)

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Install observability components using a local chart package in an offline environment.

```bash
helm upgrade --install -n univer-observability --create-namespace \
    --set global.univerNamespace="univer" \
    -f your-own-values-observability.yaml-path \
    univer-observability \
    univer-observability-xxxx.tgz
```

--------------------------------

### Manage Docker Compose Services

Source: https://docs.univer.ai/guides/pro/troubleshooting

Commands to start services, check status, and inspect logs for specific containers.

```bash
cd univer-server
bash run.sh start
docker compose ps
docker compose logs --tail=200 <service>
```

--------------------------------

### Deploy Univer via Helm (Offline)

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Install the Univer stack using a local chart package in an offline environment.

```bash
helm install -n univer --create-namespace \
    -f your-own-values.yaml-path \
    --set global.istioNamespace="univer" \
    --set-file universer.license.licenseV2=your-license.txt-path \
    --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path \
    univer-stack \
    univer-stack-xxxx.tgz # Change to the corresponding chart package in the current directory after extraction

# After success, run the following two commands to restart services to complete sidecar injection
kubectl rollout restart -n univer deployment/collaboration-server
kubectl rollout restart -n univer deployment/universer
```

--------------------------------

### Deploy Univer via Helm (Online)

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Use this command to install the Univer stack when the server has public internet access. Follow up with rollout restarts to ensure sidecar injection.

```bash
helm install -n univer --create-namespace \
    -f your-own-values.yaml-path \
    --set global.istioNamespace="univer" \
    --set-file universer.license.licenseV2=your-license.txt-path \
    --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path \
    univer-stack \
    oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \
    --version target-version

# After success, run the following two commands to restart services to complete sidecar injection
kubectl rollout restart -n univer deployment/collaboration-server
kubectl rollout restart -n univer deployment/universer
```

--------------------------------

### Deploy License via Helm

Source: https://docs.univer.ai/guides/pro/license

Use Helm to upgrade or install the Univer stack with license file paths provided as set-file arguments.

```bash
helm upgrade --install -n univer --create-namespace \
--set global.istioNamespace="univer" \
--set-file universer.license.licenseV2=$(YOUR_LICENSE_TXT_PATH) \
--set-file universer.license.licenseKeyV2=$(YOUR_LICENSE_KEY_TXT_PATH) \
univer-stack oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack
```

--------------------------------

### Install New Kubernetes Version via Helm

Source: https://docs.univer.ai/guides/pro/downtime-upgrade

Deploy the target version of the stack using Helm with the provided configuration and license files.

```bash
helm upgrade --install univer-stack \
  oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \
  --version target-version \
  -n univer \
  -f your-values.yaml-path \
  --set-file universer.license.licenseV2=your-license.txt-path \
  --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path
```

--------------------------------

### Update Exchange Configuration

Source: https://docs.univer.ai/guides/pro/troubleshooting

Example configuration line for the exchange service template.

```yaml
addr: no-txt:///${TEMPORAL_HOST}:${TEMPORAL_PORT}
```

--------------------------------

### GET /universer-api/snapshot/{type}/unit/{unitID}/rev/0/ensure

Source: https://docs.univer.ai/guides/pro/api

Creates a snapshot for a document.

```APIDOC
## GET /universer-api/snapshot/{type}/unit/{unitID}/rev/0/ensure

### Description
Ensures a snapshot exists for the specified document.

### Method
GET

### Endpoint
/universer-api/snapshot/{type}/unit/{unitID}/rev/0/ensure

### Parameters
#### Path Parameters
- **type** (enum(int)) - Required - 1 (doc), 2 (sheet)
- **unitID** (string) - Required - Document ID
```

--------------------------------

### User Role Request and Response

Source: https://docs.univer.ai/guides/pro/usip

Example cURL request to retrieve user roles for a specific document and the resulting JSON response.

```bash
curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"
```

```json
{
  "userID": "acd5455e44fc5bb55",
  "role": "editor"
}
```

--------------------------------

### Load offline Docker images

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Execute this script after extracting the offline installation package to load images into the local Docker environment.

```bash
bash load-images.sh
```

--------------------------------

### Initialize Univer Pro Starter Kit

Source: https://docs.univer.ai/guides/pro

Commands to clone and run the starter kit using npm or pnpm package managers.

```bash
npx degit dream-num/univer-pro-sheet-start-kit univer-pro-sheet-start-kit
cd univer-pro-sheet-start-kit
npm install
npm run dev
```

```bash
pnpm dlx degit dream-num/univer-pro-sheet-start-kit univer-pro-sheet-start-kit
cd univer-pro-sheet-start-kit
pnpm install
pnpm dev
```

--------------------------------

### GET /universer-api/snapshot/{type}/units

Source: https://docs.univer.ai/guides/pro/api

Retrieves a list of documents.

```APIDOC
## GET /universer-api/snapshot/{type}/units

### Description
Lists documents of a specific type with pagination support.

### Method
GET

### Endpoint
/universer-api/snapshot/{type}/units

### Parameters
#### Path Parameters
- **type** (enum(int)) - Required - 1 (doc), 2 (sheet)

#### Query Parameters
- **nextCursor** (string) - Optional - Next page cursor

### Response
#### Success Response (200)
- **units** (array[object]) - List of documents
- **nextCursor** (string) - Cursor for the next page
```

--------------------------------

### GET /universer-api/exchange/task/{taskID}

Source: https://docs.univer.ai/guides/pro/api

Polls the status of an import or export task.

```APIDOC
## GET /universer-api/exchange/task/{taskID}

### Description
Retrieves the status and result details of a background task.

### Method
GET

### Endpoint
/universer-api/exchange/task/{taskID}

### Parameters
#### Path Parameters
- **taskID** (string) - Required - Task id

### Response
#### Success Response (200)
- **error** (object) - Error details
- **code** (enum(int)) - 1 (success)
- **message** (string) - Error message
- **status** (enum(string)) - "pending", "done", "failed"
- **export** (object) - Export result details
- **fileID** (string) - Exported file id
- **import** (object) - Import result details
- **unitID** (string) - Imported unitID
- **jsonID** (string) - JSON file id

#### Response Example
{
  "error": {
    "code": 1,
    "message": ""
  },
  "status": "done",
  "export": {
    "fileID": "456"
  },
  "import": {
    "unitID": "789",
    "jsonID": "012"
  }
}
```

--------------------------------

### Run Deployment Scripts

Source: https://docs.univer.ai/guides/pro/components

Commands to initiate deployment for Docker Compose and Kubernetes environments.

```bash
bash run.sh
```

```bash
helm install -n univer --create-namespace \
  --set global.istioNamespace="univer" \
  --values values.yaml \
  univer-stack oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack
kubectl rollout restart -n univer deployment/collaboration-server
kubectl rollout restart -n univer deployment/universer
```

--------------------------------

### GET /universer-api/file/{fileID}/sign-url

Source: https://docs.univer.ai/guides/pro/api

Generates a signed download URL for a processed file.

```APIDOC
## GET /universer-api/file/{fileID}/sign-url

### Description
Retrieves a temporary download URL for a file identified by its FileID.

### Method
GET

### Endpoint
/universer-api/file/{fileID}/sign-url

### Parameters
#### Path Parameters
- **fileID** (string) - Required - Result file id

### Response
#### Success Response (200)
- **error** (object) - Error details
- **code** (enum(int)) - 1 (success)
- **message** (string) - Error message
- **url** (string) - Download URL

#### Response Example
{
  "error": {
    "code": 1,
    "message": ""
  },
  "url": "https://example.com/path/to/file.xlsx"
}
```

--------------------------------

### GET /user-role

Source: https://docs.univer.ai/guides/pro/usip

Determines the permissions (owner, editor, reader) for a specific user on a specific document.

```APIDOC
## GET /user-role

### Description
Determines the permissions (owner, editor, reader) for a specific user on a specific document.

### Method
GET

### Query Parameters
- **userID** (string) - Required - User ID
- **unitID** (string) - Required - Document ID
- **metaData** (string) - Optional - Metadata associated with the unit (v0.20.0+)

### Request Example
curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"

### Response
#### Success Response (200)
- **userID** (string) - User ID in request
- **role** (string) - Role: owner, editor, reader

### Response Example
{
  "userID": "acd5455e44fc5bb55",
  "role": "editor"
}
```

--------------------------------

### Enable Univer Event Publishing

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Activate event synchronization by setting the EVENT_SYNC flag.

```text
EVENT_SYNC=true # Set to true to enable
```

--------------------------------

### Manage Univer Server Services

Source: https://docs.univer.ai/guides/pro/server

Standard commands for controlling the lifecycle of the server instance.

```bash
cd univer-server && bash run.sh stop
```

```bash
cd univer-server && bash run.sh start
```

```bash
cd univer-server && bash run.sh restart
```

```bash
cd univer-server && bash run.sh uninstall
```

--------------------------------

### GET /user-authentication

Source: https://docs.univer.ai/guides/pro/usip

Authenticates a user by forwarding request headers to the implementation. This is triggered on every request between the client and server.

```APIDOC
## GET /user-authentication

### Description
Authenticates a user by forwarding request headers to the implementation. This is triggered on every request between the client and server.

### Method
GET

### Response
#### Success Response (200)
- **user** (Object) - Returned on successful authentication
- **userID** (string) - User ID (recommend open_uid)
- **name** (string) - Display name for collaborators
- **avatar** (string) - Avatar URL for collaborators

### Response Example
{
  "user": {
    "userID": "ace55655ceabd55g",
    "name": "alice",
    "avatar": "https://image.xx/acde55acb45bbead55"
  }
}
```

--------------------------------

### Configure PostgreSQL Credentials

Source: https://docs.univer.ai/guides/pro/components

Set PostgreSQL database credentials for initial deployment.

```text
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
```

```yaml
global:
  postgresql:
    auth:
      postgresPassword: postgres

universer:
  config:
    database:
      username: postgres
      password: postgres

temporal:
  server:
    config:
      persistence:
        default:
          sql:
            user: postgres
            password: postgres

        visibility:
          sql:
            user: postgres
            password: postgres
```

--------------------------------

### Get Signed File URL via cURL

Source: https://docs.univer.ai/guides/pro/api

Generates a temporary download URL for a processed file using its fileID.

```bash
curl -X GET 'http://localhost:8000/universer-api/file/1234/sign-url'
```

--------------------------------

### Get Task Result via cURL

Source: https://docs.univer.ai/guides/pro/api

Retrieves the status and result details of a previously initiated import or export task.

```bash
curl -X GET 'http://localhost:8000/universer-api/exchange/task/123'
```

--------------------------------

### Configure License in Preset Mode

Source: https://docs.univer.ai/guides/pro/license

Inject the license content directly into the UniverSheetsAdvancedPreset during initialization.

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'

const { univerAPI } = createUniver({
  presets: [
    UniverSheetsAdvancedPreset({
      license: `Content from license.txt`,
    }),
  ],
})
```

--------------------------------

### Check Demo UI Port

Source: https://docs.univer.ai/guides/pro/troubleshooting

Command to identify processes using the Demo UI port.

```bash
lsof -i :3010
```

--------------------------------

### Fork Document API

Source: https://docs.univer.ai/guides/pro/api

Creates a copy of an existing document. This is an experimental API.

```bash
curl -X POST 'http://localhost:8000/universer-api/snapshot/2/unit/ETVf-B4lQqOSE_p09mcp9Q/fork'
```

```json
{
  "error": {
    "code": 1,
    "message": ""
  },
  "unitId": "FORKED_ETVf-B4lQqOSE_p09mcp9Q"
}
```

--------------------------------

### Configure RabbitMQ Credentials

Source: https://docs.univer.ai/guides/pro/components

Set RabbitMQ username and password for initial deployment.

```text
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=guest
```

```yaml
rabbitmq:
  auth:
    username: guest
    password: guest

universer:
  config:
    rabbitmq:
      username: guest
      password: guest
```

--------------------------------

### Enable Object Permission Inheritance

Source: https://docs.univer.ai/guides/pro/usip

Configure settings to allow document owners to inherit full permissions over sub-objects.

```text
AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true
```

```yaml
universer:
  config:
    auth:
      permission:
        enableObjInherit: true
```

--------------------------------

### Register HTTP Interceptor for PresetPlugin

Source: https://docs.univer.ai/guides/pro/usip

Configures custom headers by registering an interceptor with the HTTPService. Choose the import based on your specific project setup.

```typescript
import { HTTPService } from '@univerjs/preset-sheets-core'

const injector = univer.__getInjector()
const httpService = injector.get(HTTPService)
httpService.registerHTTPInterceptor({
  priority: 0,
  interceptor: (request, next) => {
    // request.headers.set('Authorization', 'Bearer your-token-here')
    return next(request)
  },
})
```

```typescript
import { HTTPService } from '@univerjs/network'

const injector = univer.__getInjector()
const httpService = injector.get(HTTPService)
httpService.registerHTTPInterceptor({
  priority: 0,
  interceptor: (request, next) => {
    // request.headers.set('Authorization', 'Bearer your-token-here')
    return next(request)
  },
})
```

--------------------------------

### Configure USIP Environment Variables

Source: https://docs.univer.ai/guides/pro/usip

Set these variables in .env.custom to enable and configure USIP endpoints and API keys.

```text
USIP_ENABLED=true
USIP_URI_CREDENTIAL=https://your-domain/usip/credential
USIP_URI_USERINFO=https://your-domain/usip/userinfo
USIP_URI_ROLE=https://your-domain/usip/role
USIP_URI_COLLABORATORS=https://your-domain/usip/collaborators
USIP_URI_UNITEDITTIME=https://your-domain/usip/unit-edit-time

USIP_APIKEY=

AUTH_PERMISSION_ENABLE_OBJ_INHERIT=false
AUTH_PERMISSION_CUSTOMER_STRATEGIES=
```

--------------------------------

### Configure Network Settings

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Modify CIDR and service ports in .env.custom to resolve conflicts with existing host services.

```text
# If it conflicts with existing network configuration, you can modify the CIDR used by docker
DOCKER_NETWORK_SUBNET=172.30.0.0/16

# Univer API service exposed port; if it conflicts with other host services, change to another port
HOST_NGINX_PORT=the-univer-server-api-port-you-wantted

# If you choose Univer's built-in MinIO as object storage and there is a port conflict, add this configuration item
# If you are using self-maintained object storage, setting this configuration item has no effect
HOST_MINIO_PORT=the-minio-port-you-wantted

# If you choose Univer's built-in observability components and there is a port conflict, add this configuration item
# If you are using self-maintained observability components, setting this configuration item has no effect
HOST_GRAFANA_PORT=the-grafana-port-you-wantted
```

--------------------------------

### Enable Univer Event Publishing

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Enable event synchronization by setting the rabbitmq eventSync flag to true in your values.yaml.

```yaml
universer:
  config:
    rabbitmq:
      eventSync: true # Set to true to enable
```

--------------------------------

### Configure USIP in Kubernetes

Source: https://docs.univer.ai/guides/pro/usip

Use the values.yaml file to define USIP settings for Kubernetes deployments.

```yaml
universer:
  config:
    usip:
      enabled: true
      uri:
        userinfo: 'https://your-domain/usip/userinfo'
        collaborators: 'https://your-domain/usip/collaborators'
        role: 'https://your-domain/usip/role'
        credential: 'https://your-domain/usip/credential'
        unitEditTime: 'https://your-domain/usip/unit-edit-time'
      apikey: ''
    auth:
      permission:
        enableObjInherit: false
        customerStrategies: ''
```

--------------------------------

### Configure Service Capacity

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Settings for scaling service instances and defining memory limits.

```text
UNIVERSER_REPLICATION_CNT=2 # universer instance count
COLLABORATION_SERVER_REPLICATION_CNT=2 # collaboration service instance count
COLLABORATION_SERVER_MEMORY_LIMIT=2048 # collaboration service max memory limit, in MB
COLLABORATION_HELPER_REPLICATION_CNT=2 # helper service instance count, note: introduced since v0.13.0
COLLABORATION_HELPER_MEMORY_LIMIT=2048 # helper max memory limit, in MB, note: introduced since v0.13.0

# import/export exchange-worker capacity-related config
EXCHANGE_WORKER_REPLICATION_CNT=1 # working exchange worker count
EXCHANGE_WORKER_MEMORY_LIMIT=4096 # MB, the memory limit of each exchange-worker.
EXCHANGE_WORKER_IMPORT_CONCURRENT=1 # how many import tasks each worker can do at the same time.
EXCHANGE_WORKER_EXPORT_CONCURRENT=1 # how many export tasks each worker can do at the same time.
```

--------------------------------

### Configure License in Plugin Mode

Source: https://docs.univer.ai/guides/pro/license

Register the UniverLicensePlugin after the Univer instance is created to apply the license.

```typescript
import { UniverLicensePlugin } from '@univerjs-pro/license'

univer.registerPlugin(UniverLicensePlugin, {
  license: `Content from license.txt`,
})
```

--------------------------------

### Configure DamengDB RDS

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Disable the default RDS and connect to an external DamengDB instance.

```text
# RDS config
DISABLE_UNIVER_RDS=true # When using your own RDS, disable Univer's default PostgreSQL

DATABASE_DRIVER=dameng
DATABASE_HOST=your-database-host
DATABASE_PORT=your-database-port
DATABASE_DBNAME=univer # Univer database init scripts use this name by default; keep it consistent if changed
DATABASE_USERNAME=user-name # Grant select, insert, update, delete permissions
DATABASE_PASSWORD=password
```

--------------------------------

### Configure USIP Authentication

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Enable identity authentication and permission management by defining USIP endpoints and settings in .env.custom.

```text
# usip about
USIP_ENABLED=true # Set to true to enable USIP
USIP_URI_CREDENTIAL=https://your-domain/usip/credential
USIP_URI_USERINFO=https://your-domain/usip/userinfo
USIP_URI_ROLE=https://your-domain/usip/role
USIP_URI_COLLABORATORS=https://your-domain/usip/collaborators
USIP_URI_UNITEDITTIME=https://your-domain/usip/unit-edit-time

# apikey is optional
USIP_APIKEY=

# auth about
AUTH_PERMISSION_ENABLE_OBJ_INHERIT=false
AUTH_PERMISSION_CUSTOMER_STRATEGIES=
```

--------------------------------

### Configure DamengDB

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Configuration for using DamengDB as the primary database for Univer.

```yaml
universer:
  config:
    database:
      driver: dameng
      host: your-database-host
      port: your-database-port
      dbname: univer # Univer database init scripts use this name by default; keep it consistent if changed
      username: dameng # Grant select, insert, update, delete permissions
      password: dameng
      sslMode: disable # Supported values: disable, require, verify-ca, verify-full; set to require / verify-ca / verify-full to enable SSL
```

--------------------------------

### Download Univer services via CLI

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Use this command to download the latest or a specific version of Univer services when the server has internet access.

```bash
bash -c "$(curl -fsSL https://get.univer.ai/product)" [-- version]
```

--------------------------------

### Configure S3 (MinIO) Credentials

Source: https://docs.univer.ai/guides/pro/components

Set MinIO S3 storage credentials for initial deployment.

```text
S3_USER=minio
S3_PASSWORD=minio123456
```

```yaml
minio:
  auth:
    rootUser: admin
    rootPassword: minioadmin

universer:
  config:
    s3:
      accessKeyID: admin
      accessKeySecret: minioadmin
```

--------------------------------

### Configure Object Storage

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Settings for connecting to an external S3-compatible object storage service.

```text
DISABLE_UNIVER_S3=true # When using your own object storage, disable Univer's built-in MinIO

# s3 config
S3_USER=user
S3_PASSWORD=password
S3_REGION=your-inner-s3like-region # If the S3-like service has no such concept, fill in any string

# S3_PATH_STYLE, can be set to true or false
# If set to true, use Path-Style to construct access URLs
# If set to false, use Virtual-Host Style to construct access URLs
S3_PATH_STYLE=true|false

# S3_ENDPOINT address provided for internal service access
S3_ENDPOINT=inner-visit-host:port

# S3_ENDPOINT_PUBLIC publicly accessible address, used when the client directly connects to object storage to download files
S3_ENDPOINT_PUBLIC=public-visit-host:port

# S3_DEFAULT_BUCKET configures which bucket to use
S3_DEFAULT_BUCKET=default-bucket-name
```

--------------------------------

### Configure Database SSL

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Settings for enabling TLS/SSL connections to the database.

```text
# database ssl config
DATABASE_SSL_MODE=require
TEMPORAL_SQL_TLS_ENABLED=true
TEMPORAL_SQL_TLS_DISABLE_HOST_VERIFICATION=true
```

--------------------------------

### Configure Message Queue

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Settings for connecting to an external RabbitMQ cluster.

```text
DISABLE_UNIVER_MQ=true # When using your own MQ, disable Univer's built-in MQ

RABBITMQ_CLUSTER_ENABLED=true # Must be set to true
RABBITMQ_CLUSTER_USERNAME=user-name # Needs Declare Exchange, Produce, Consume permissions
RABBITMQ_CLUSTER_PASSWORD=password # password

# use comma to separate multiple addresses
# for example: RABBITMQ_CLUSTER_ADDR=192.168.1.2:5672,192.168.1.5:5672,192.168.1.7:5672
# Every addr must be readable and writable; Univer will poll the hosts until a connection succeeds
RABBITMQ_CLUSTER_ADDR=host:port[,host:port]

# RABBITMQ_CLUSTER_VHOST is the vhost of the rabbitmq cluster. If you don't set it, the default value is /
# for example: RABBITMQ_CLUSTER_VHOST=univer
RABBITMQ_CLUSTER_VHOST=/
RABBITMQ_CLUSTER_SCHEMA=amqp
```

--------------------------------

### Create Document API

Source: https://docs.univer.ai/guides/pro/api

Creates a new document or sheet. Requires a JSON body with type, name, and creator fields.

```bash
curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \
    -X POST \
    -H 'Content-Type: application/json' \
    --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'
```

```json
{
  "error": {
    "code": 1,
    "message": "success"
  },
  "unitID": "ETVf-B4lQqOSE_p09mcp9Q"
}
```

--------------------------------

### Configure GaussDB

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Configuration for using GaussDB as the primary database for Univer.

```yaml
universer:
  config:
    database:
      driver: gaussdb
      host: your-database-host
      port: your-database-port
      dbname: univer # Univer database init scripts use this name by default; keep it consistent if changed
      username: gaussdb # Grant select, insert, update, delete permissions
      password: gaussdb
      sslMode: disable # Supported values: disable, require, verify-ca, verify-full; set to require / verify-ca / verify-full to enable SSL
```

--------------------------------

### POST /universer-api/snapshot/{type}/unit/-/create

Source: https://docs.univer.ai/guides/pro/api

Creates a new document of the specified type.

```APIDOC
## POST /universer-api/snapshot/{type}/unit/-/create

### Description
Creates a new document (Docs or Sheets) with the provided name and creator information.

### Method
POST

### Endpoint
/universer-api/snapshot/{type}/unit/-/create

### Parameters
#### Path Parameters
- **type** (enum(int)) - Required - 1 (docs), 2 (sheets)

#### Request Body
- **type** (enum(int)) - Required - 1 (docs), 2 (sheets)
- **name** (string) - Required - Document name
- **creator** (string) - Required - Creator id
- **idempotencyKey** (string) - Optional - Idempotency key (max 64 bytes)
- **metaData** (string) - Optional - User-defined information (max 1024 bytes)

### Response
#### Success Response (200)
- **error** (object) - Error details
- **unitID** (string) - The ID of the created document
```

--------------------------------

### Configure RabbitMQ in values.yaml

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Sets up RabbitMQ cluster connection details and allows disabling the built-in RabbitMQ instance.

```yaml
universer:
  config:
    rabbitmq:
      cluster:
        enabled: true # Must be set to true
        # use comma to separate multiple addresses
        # for example: RABBITMQ_CLUSTER_ADDR=192.168.1.2:5672,192.168.1.5:5672
        # Every addr must be readable and writable; Univer will poll the hosts until a connection succeeds
        addr: '192.168.1.2:5672,192.168.1.5:5672'
        username: user-here
        password: password-here
        vhost: /
        schema: amqp

rabbitmq:
  enabled: false # Disable Univer's built-in RabbitMQ
```

--------------------------------

### Configure Identity Authentication and Permission Management

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Use this configuration in a custom values.yaml file to enable USIP and define endpoint URIs.

```yaml
universer:
  config:
    usip:
      enabled: true # Set to true to enable USIP
      uri:
        userinfo: 'https://your-domain/usip/userinfo'
        collaborators: 'https://your-domain/usip/collaborators'
        role: 'https://your-domain/usip/role'
        credential: 'https://your-domain/usip/credential'
        unitEditTime: 'https://your-domain/usip/unit-edit-time'

      # apikey is optional
      apikey: ''
    auth:
      permission:
        enableObjInherit: false
        customerStrategies: ''
```

--------------------------------

### Enable Event Sync in Kubernetes

Source: https://docs.univer.ai/guides/pro/event-sync

Configure the eventSync flag within the rabbitmq section of your values.yaml file.

```yaml
universer:
  config:
    rabbitmq:
      eventSync: true
```

--------------------------------

### Configure PostgreSQL-Compatible RDS

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Use this configuration to connect Univer and Temporal to an external PostgreSQL-compatible database.

```yaml
postgresql:
  enabled: false # Disable Univer's built-in database

universer:
  config:
    database:
      driver: postgresql # Set to postgresql for PostgreSQL-compatible databases
      host: your-database-host
      port: your-database-port
      dbname: univer # Univer database init scripts use this name by default; keep it consistent if changed
      username: postgres # Grant select, insert, update, delete permissions
      password: postgres
      sslMode: disable # Supported values: disable, require, verify-ca, verify-full; set to require / verify-ca / verify-full to enable SSL

temporal: # temporal uses the database
  server:
    config:
      persistence:
        default:
          driver: sql # Fixed to sql
          sql:
            driver: postgres12 # postgres 12 or above required
            host: your-database-host
            port: your-database-port
            database: temporal # Univer database init scripts use this name by default; keep it consistent if changed
            user: postgres # Grant select, insert, update, delete permissions
            password: postgres

        visibility:
          driver: sql
          sql:
            driver: postgres12 # postgres 12 or above required
            host: your-database-host
            port: your-database-port
            database: temporal_visibility # Univer database init scripts use this name by default; keep it consistent if changed
            user: postgres # Grant select, insert, update, delete permissions
            password: postgres
```

--------------------------------

### Collect Troubleshooting Logs

Source: https://docs.univer.ai/guides/pro/troubleshooting

Script to aggregate logs from temporal and universer services into a compressed archive.

```bash
mkdir -p logs_collect && \
docker compose logs temporal > logs_collect/temporal.log 2>&1 && \
docker compose logs universer > logs_collect/universer.log 2>&1 && \
tar czf univer-troubleshoot-logs.tar.gz logs_collect
```

--------------------------------

### Rollback Kubernetes Stack

Source: https://docs.univer.ai/guides/pro/downtime-upgrade

Revert to the previous version and configuration using Helm.

```bash
helm upgrade --install univer-stack \
  oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \
  --version old-version \
  -n univer \
  -f old-values.yaml \
  --set-file universer.license.licenseV2=your-license.txt-path \
  --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path
```

--------------------------------

### Configure PostgreSQL-Compatible RDS

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Disable the default RDS and connect to an external PostgreSQL-compatible database.

```text
# RDS config
DISABLE_UNIVER_RDS=true # When using your own RDS, disable Univer's default PostgreSQL

DATABASE_DRIVER=postgresql # Set to postgresql for PostgreSQL-compatible databases
DATABASE_HOST=your-database-host
DATABASE_PORT=your-database-port
DATABASE_DBNAME=univer # Univer database init scripts use this name by default; keep it consistent if changed
DATABASE_USERNAME=user-name # Grant select, insert, update, delete permissions
DATABASE_PASSWORD=password
```

--------------------------------

### Load Offline Images

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Load container images into a private registry for offline deployment environments.

```bash
export REGISTER=XXXX # Your private image registry
export NAMESPACE=XXX # The image namespace to upload to
docker login $REGISTER
bash load-image.sh --registry $REGISTER --namespace $NAMESPACE
```

--------------------------------

### Configure GaussDB RDS

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Disable the default RDS and connect to an external GaussDB instance.

```text
# RDS config
DISABLE_UNIVER_RDS=true # When using your own RDS, disable Univer's default PostgreSQL

DATABASE_DRIVER=gaussdb
DATABASE_HOST=your-database-host
DATABASE_PORT=your-database-port
DATABASE_DBNAME=univer # Univer database init scripts use this name by default; keep it consistent if changed
DATABASE_USERNAME=user-name # Grant select, insert, update, delete permissions
DATABASE_PASSWORD=password
```

--------------------------------

### Configure MySQL-Compatible RDS

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Use this configuration to connect Univer and Temporal to an external MySQL-compatible database.

```yaml
postgresql:
  enabled: false # Disable Univer's built-in database

universer:
  config:
    database:
      driver: mysql # Set to mysql for MySQL-compatible databases
      host: your-database-host
      port: your-database-port
      dbname: univer # Univer database init scripts use this name by default; keep it consistent if changed
      username: mysql # Grant select, insert, update, delete permissions
      password: mysql
      sslMode: disable # Supported values: disable, require, verify-ca, verify-full; set to require / verify-ca / verify-full to enable SSL

temporal:
  server:
    config:
      persistence:
        default:
          driver: sql
          sql:
            driver: mysql8 # MySQL 8.x required
            host: your-database-host
            port: your-database-port
            database: temporal # Univer database init scripts use this name by default; keep it consistent if changed
            user: mysql # Grant select, insert, update, delete permissions
            password: mysql

        visibility:
          driver: sql
          sql:
            driver: mysql8
            host: your-database-host
            port: your-database-port
            database: temporal_visibility # Univer database init scripts use this name by default; keep it consistent if changed
            user: mysql
            password: mysql
```

--------------------------------

### Kubernetes Diagnostic Commands

Source: https://docs.univer.ai/guides/pro/troubleshooting

Commands for inspecting pod status, viewing logs, and checking ingress/endpoint configuration.

```bash
kubectl describe pod <pod> -n univer
```

```bash
kubectl logs <pod> -n univer --previous
```

```bash
dig univer.example.com
kubectl get ingress -n univer
kubectl get endpoints -n univer
```

--------------------------------

### Enable Event Sync in Docker Compose

Source: https://docs.univer.ai/guides/pro/event-sync

Set the EVENT_SYNC environment variable to true in your .env.custom file to enable the feature.

```text
EVENT_SYNC=true
```

--------------------------------

### Configure Service Capacity in values.yaml

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Sets replica counts and resource limits for various Univer services and workers.

```yaml
universer:
  replicaCount: 3 # universer instance count
collaboration-server:
  replicaCount: 3 # collaboration service instance count
  maxMemoryLimit: 2048 # MB, collaboration service max memory limit
collaboration-helper-server: # Note: introduced since v0.13.0
  replicaCount: 2 # helper service instance count
worker:
  replicaCount: 1 # working exchange worker count
  temporalWorker:
    importConcurrent: 1 # how many import tasks each worker can do at the same time.
    exportConcurrent: 1 # how many export tasks each worker can do at the same time.
```

--------------------------------

### Configure Cross-Origin Resource Sharing

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Define allowed origins and headers for CORS in the .env.custom file.

```text
# allowed cross-origins config
CORS_ALLOW_ORIGINS='["domain1", "domain2", "and more"]'
CORS_ALLOW_HEADERS='["content-type","authorization"]'
```

--------------------------------

### Configure MySQL-Compatible RDS

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Disable the default RDS and connect to an external MySQL-compatible database.

```text
# RDS config
DISABLE_UNIVER_RDS=true # When using your own RDS, disable Univer's default PostgreSQL

DATABASE_DRIVER=mysql # Set to mysql for MySQL-compatible databases
DATABASE_HOST=your-database-host
DATABASE_PORT=your-database-port
DATABASE_DBNAME=univer # Univer database init scripts use this name by default; keep it consistent if changed
DATABASE_USERNAME=user-name # Grant select, insert, update, delete permissions
DATABASE_PASSWORD=password
```

--------------------------------

### Configure values.yaml for Kubernetes Deployment

Source: https://docs.univer.ai/guides/pro/deploy/kubernetes

Use this configuration to define service replicas, external database connections, S3 storage, and USIP authentication settings for a Univer Kubernetes deployment.

```yaml
collaboration-demo:
  enabled: false # Set to false to disable deploying the demo service

postgresql:
  enabled: false # Disable Univer's built-in database

minio:
  enabled: false # Disable Univer's built-in MinIO

collaboration-server:
  replicaCount: 5
  maxMemoryLimit: 2048

universer:
  replicaCount: 4
  ingress:
    enabled: true
    hosts:
      - host: usip-demo.univer.ai # Change to your actual domain
        paths:
          - path: /universer-api/
            pathType: Prefix
  config:
    usip:
      enabled: true # Set to true to enable USIP
      uri:
        userinfo: 'https://usip-demo.univer.ai/usip/userinfo'
        collaborators: 'https://usip-demo.univer.ai/usip/collaborators'
        role: 'https://usip-demo.univer.ai/usip/role'
        credential: 'https://usip-demo.univer.ai/usip/credential'
        unitEditTime: 'https://usip-demo.univer.ai/usip/unit-edit-time'
    auth:
      permission:
        customerStrategies: '[ {"action": 3, "role": 2}, {"action": 6, "role": 2} ]'
    rabbitmq:
      eventSync: true # Set to true to enable
    database:
      driver: postgresql
      host: univer-postgresql
      port: 5432
      dbname: univer
      username: universer-biz
      password: 123456
      sslMode: disable # Supported values: disable, require, verify-ca, verify-full; set to require / verify-ca / verify-full to enable SSL
    s3:
      accessKeyID: universer-biz
      accessKeySecret: 123456
      region: cn-sz
      endpoint: 'univer-s3:9652'
      endpointPublic: 'univer.ai:9653'
      usePathStyle: true
      defaultBucket: univer

temporal:
  server:
    config:
      persistence:
        default:
          driver: sql
          sql:
            driver: postgres12
            host: univer-postgresql
            port: 5432
            database: temporal
            user: universer-temporal
            password: 123456

        visibility:
          driver: sql
          sql:
            driver: postgres12
            host: univer-postgresql
            port: 5432
            database: temporal_visibility
            user: universer-temporal
            password: 123456
```

--------------------------------

### Triage Commands

Source: https://docs.univer.ai/guides/pro/troubleshooting

Initial diagnostic commands for checking connectivity, service status, and Kubernetes pod health.

```bash
curl -I https://get.univer.ai
```

```bash
cd univer-server && bash run.sh start
```

```bash
docker compose ps
```

```bash
kubectl describe pod
```

--------------------------------

### Enable Observability Components

Source: https://docs.univer.ai/guides/pro/deploy/docker-compose

Configuration for enabling and securing the built-in Grafana observability dashboard.

```text
# observability config
ENABLE_UNIVER_OBSERVABILITY=true # Set to true to enable
GRAFANA_USERNAME=set-your-admin-user-name-here # Set Grafana admin username
GRAFANA_PASSWORD=set-your-admin-user-password-here # Set Grafana admin password
HOST_GRAFANA_PORT=set-the-port-you-want # Grafana exposed port
```

--------------------------------

### Import a file

Source: https://docs.univer.ai/guides/pro/import-export

Initiates an import request and polls for completion. Requires a valid file ID from the upload step.

```typescript
interface ImportParams {
  fileID: string
  type: 1 | 2 // 1 = doc, 2 = sheet
  outputType: 1 | 2 // 1 = unit, 2 = json
  minSheetRowCount?: number
  minSheetColumnCount?: number
}

async function importFile(params: ImportParams): Promise<string> {
  const res = await fetch(
    `${BASE_URL}/universer-api/exchange/${params.type}/import`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // cookie: '_univer=XXXXXX',
      },
      body: JSON.stringify({
        fileID: params.fileID,
        outputType: params.outputType,
        minSheetRowCount: params.minSheetRowCount ?? 1000,
        minSheetColumnCount: params.minSheetColumnCount ?? 20,
      }),
    },
  )

  const data = await res.json()
  if (data.error?.code !== 1) {
    throw new Error(data.error?.message || 'Import request failed')
  }

  // Poll until the task is done or failed
  const taskResult = await pollTask(data.taskID)
  if (taskResult.status === 'failed') {
    throw new Error(taskResult.error?.message || 'Import failed')
  }

  return params.outputType === 1
    ? taskResult.import!.unitID!
    : taskResult.import!.jsonID!
}
```

--------------------------------

### Upgrade Kubernetes Stack via Helm

Source: https://docs.univer.ai/guides/pro/downtime-upgrade

Use Helm to upgrade the stack with specific configuration files and license paths.

```bash
helm upgrade univer-stack \
  oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \
  --version your-current-version \
  -n univer \
  -f values-1.0.0-forbid.yaml \
  --set-file universer.license.licenseV2=your-license.txt-path \
  --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path
```
Tokens:
Raw