常见问题&疑难解答 FAQ

Q: 私有化需要的服务器配置和环境如何？

A：请查阅vika私有化服务所需的服务器配置

Q: 私有化支持对接飞书、企微和钉钉？

A：支持，通过自建应用的方式进行接入

企微接入： 企业微信 x vika

钉钉接入： 钉钉 x vika

飞书接入：飞书 x vika

Q: 支持接入内部员工身份认证平台SSO？

A：支持，可自助接入vika身份认证API接口，实现单点登录和组织架构实时同步，接入方式请参考「SSO集成」

集成SSO，务必配置 backend-server 服务 的环境变量：

Auth

ONEACCESS_ENABLED

Whether enable oneaccess sso, only for enterprise

false

Auth

ONEACCESS_IAM_HOST

身份认证系统 Server Host地址

http://127.0.0.1

Auth

ONEACCESS_CLIENT_ID

客户端应用 ID (由身份认证系统提供).
参考 document

Auth

ONEACCESS_CLIENT_SECRET

客户端应用 secret (由身份认证系统提供) .
参考 document

Auth

ONEACCESS_ENCRYPT_KEY

AES 加密key, default is 123456

123456

SERVER

SERVER_DOMAIN

服务域名, 如 http(s)://example.com

““

Q: 系统内是否有超级管理后台和超级管理员员帐号？

A：vika没有超级管理后台和超级管理员帐号，但是空间站的创建者可以管理该空间站，若有需求需要做一个管理后台，可定制开发。

Q：如何配置邮件推送服务，接入自有SMTP Server？

A：默认情况下， 私有化不提供任何第三方服务，包括邮件推送服务，这意味着您无法邀请用户，因为它需要电子邮件发送功能。

另外，您可自行配置 SMTP 服务器修改环境变量，并重启后端服务backend-server。

MAIL_ENABLED=true
MAIL_HOST=smtp.xxx.com
MAIL_PASSWORD=your_email_password
MAIL_PORT=465
MAIL_SSL_ENABLE=true
MAIL_STARTTLS_ENABLE=true
MAIL_STARTTLS_REQUIRED=true
MAIL_TYPE=smtp
MAIL_USERNAME=your_email

POC 版本变量配置方法

k8s版本配置方法

收不到邮件?

排查方法: 查看 backend-server日志, 关键字mail 相关的报错.常见报错

  • MAIL_HOST 连接失败, 检查网络和地址是否正常

  • 认证失败, 检查用户/密码是否正常.

Q：可以更换logo、文案吗？

A：可以，自定义LOGO属于增值服务，该服务可以根据客户需求，支持自定义LOGO、文案、一些提示语、提示图与教学视频、跳转的URL等总共有6000+项配置，请联系销售顾问沟通。

Q：是否支持短信接入？没有接入短信/邮箱验证码情况下，如何删除空间站？

A：短信平台涉及短信模板审核，vika私有化目前不支持短信接入。

登录数据库，执行SQL

UPDATE vika_unit_member SET is_deleted = 1 WHERE space_id = 'spcXXXX';

Q: 单机版和集群版推护有什么区别?

A: 单机版采用 docker-compose 部署,维护指令主要是docker-compose

集群版采用 k8s 部署,维护指令主要是 ops-manager 和 kubectl

如: 重启单个服务方法, 单机版 vs 集群版.

Q: 默认是单表API调用5 qps，怎么调整配置

调整 5QPS 会影响性能,谨慎操作 。

A: 全局环境变量配置 LIMIT_POINTS=50，调整到 50qps 。单机版重启room-server，集群版重启fusion-server

更多配置说明，可自行查看「环境变量」

Q: 默认是单表列数上限，怎么调整配置

A: room-server环境变量配置 SERVER_MAX_FIELD_COUNT=200，调整到 2500列 。单机版重启room-server，集群版重启room-server

更多配置说明，可自行查看「环境变量」

Q: 创建记录API接口，单次请求最多创建10条记录，怎么调整配置

A: fusion-server环境变量配置 API_MAX_MODIFY_RECORD_COUNTS=20，调整到单次请求创建最多 20条 。单机版重启room-server，集群版重启fusion-server

更多配置说明，可自行查看「环境变量」

Q: 发布自建小程序时报错，如何解决？

发布小程序时，报错信息如图：

发布小程序报错截图

发布小程序报错截图

A: 解决方案：

  1. 安装 apitable/widget-cli

    widgetc-cli 版本 >= 1.0.7-alpha.0

npm install @apitable/widget-cli@1.0.7-alpha.0 -g

  1. 代码工程里所有 vikadata 的依赖替换为 APItable

  2. 终端执行

windows：进入 git bash 终端执行

widget-cli release --uploadHost https://xxx

mac:

widget-cli release --uploadHost https://xxx

Q: 专有云私有化，维格表开放API接口 Fusion SDK 如何使用？

A: Python 版示例

from vika import Vika
vika = Vika("_替换成你的API_Token_")
# 替换专有云地址，如 https://poc-preview.vika.ltd
vika.set_api_base("_替换成你的环境地址")     
# 通过 datasheetId 来指定要从哪张维格表操作数据。
datasheet = vika.datasheet("dstUywGjEsQTTPddvB", field_key="name")

Q: 如何上架全局小程序？

A: 方式一：登录数据库，执行以下SQL，指定某个自建小程序调整为全局小程序

UPDATE vika_widget_package SET release_type = 1 WHERE package_id = 'wpkid'

方式二：使用GM管理员账号的token，发布小程序使用

widget-cli release -g


Q：如何下架小程序？

A: 例如：下架「 图表」小程序的SQL

update vika_widget_package set is_deleted = 1 where package_id='wpkid';

Q：所有表格机器人没有正常触发，如何解决？

A: 检查以下环境变量是否正确,并重启room-server

vika 版本：ROBOT_OFFICIAL_SERVICE_SLUG=vika

apitable 版本： ROBOT_OFFICIAL_SERVICE_SLUG=apitable

Q: init-settings 镜像拉取不到

默认init-settings 路径在 vikadata/vika-ee ,如：docker.vika.ltd/vikadata/vika-ee/init-settings:v0.20.0-alpha_build1363

A: 有两种方法可更改init-settings镜像路径， 如docker.vika.ltd/vikadata/vika-ee-example/init-settings:v0.20.0-alpha_build1000

方法1. 将镜像namespace 调整为 vika-ee ,再上传

docker tag docker.vika.ltd/vikadata/vika-ee-example/init-settings:v0.20.0-alpha_build1000 docker.vika.ltd/vikadata/vika-ee/init-settings:v0.20.0-alpha_build1000

docker push docker.vika.ltd/vikadata/vika-ee/init-settings:v0.20.0-alpha_build1000

方法2. 在config.yaml设置init-settings 镜像namepsace 路径

image:
  namespace:
    app:
      custom:
        init_settings: vikadata/vika-ee-example

Q: 支持集成什么类型对象存储, 如何配置

目前支持三种对存储：

  • 七牛云

  • minio

  • 腾讯云COS

桶读写策略: 公有读私有写

七牛云相关配置config.yaml：

  • 桶: assets

  • 域名: https://s1.apitable.com

config:
  common:
    ASSETS_URL: "https://s1.apitable.com"
    ASSETS_BUCKET: "assets"
    OSS_HOST: "https://s1.apitable.com"
  custom:
    backend_server:
        OSS_CLIENT_TYPE: "aws"
        AWS_ACCESS_KEY: "替换secretid"
        AWS_ACCESS_SECRET: "替换secretKey"
        AWS_ENDPOINT: "s3-cn-south-1.qiniucs.com"
        AWS_REGION: "cn-south-1"
        ASSETS_LTD_URL: "https://s1.apitable.com"  //v0.20.0 版本后废弃 
        ASSETS_LTD_BUCKET: "assets"                //v0.20.0 版本后废弃 
        ASSETS_URL: "https://s1.apitable.com"
        ASSETS_BUCKET: "assets"

腾讯云COS相关配置config.yaml：

  • 桶: vikadata-1254196833

  • 域名: cos.ap-guangzhou.myqcloud.com

  • 区域： ap-guangzhou

config:
  common:
    ASSETS_URL: "https://cos.ap-guangzhou.myqcloud.com/vikadata-1254196833"
    ASSETS_BUCKET: "vikadata-1254196833"
    OSS_HOST: "https://cos.ap-guangzhou.myqcloud.com/vikadata-1254196833"
  custom:
    backend_server:
        OSS_CLIENT_TYPE: "aws"
        AWS_ACCESS_KEY: "替换access_key"
        AWS_ACCESS_SECRET: "替换secretKey"
        AWS_ENDPOINT: "https://cos.ap-guangzhou.myqcloud.com"
        AWS_REGION: "ap-guangzhou"
        ASSETS_LTD_URL: "https://cos.ap-guangzhou.myqcloud.com/vikadata-1254196833"  //v0.20.0 版本后废弃  
        ASSETS_LTD_BUCKET: "vikadata-1254196833"                                     //v0.20.0 版本后废弃  
        ASSETS_URL: "https://cos.ap-guangzhou.myqcloud.com/vikadata-1254196833"
        ASSETS_BUCKET: "vikadata-1254196833"

minio相关配置config.yaml：

  • 桶: assets

  • 域名: minio.vika-datacenter

config:
  common:
    ASSETS_URL: "assets"
    ASSETS_BUCKET: "assets"
    OSS_HOST: "/assets"
  custom:
    backend_server:
        OSS_CLIENT_TYPE: "aws"
        AWS_ACCESS_KEY: "替换secretid"
        AWS_ACCESS_SECRET: "替换secretKey"
        AWS_ENDPOINT: "http://minio.vika-datacenter:9000"
        ASSETS_LTD_URL: "assets"    //v0.20.0 版本后废弃  
        ASSETS_LTD_BUCKET: "assets" //v0.20.0 版本后废弃  
        ASSETS_URL: "assets"
        ASSETS_BUCKET: "assets"

Q: 查看前端的版本和变量

A: 在浏览器打开控制台，可以看下前端版本信息，如： Current version number: v0.20.0-op_build3619

更多变量可在控制台输入：__initialization_data__.envVars.变量名

Q: 通过fusion api 上传文件失败，通过前端上传文件成功

两者上传方式不一样： 前端采用直传方式， fusion 转发到 backend-server 完成上传

A: 看下接口返回报错信息，如下情况是backend-server 异常

Q: 当线上出现故障时，如何分工和快速排查

一般从网关响应码、服务节点状态和数据库三方面入手

  1. 查看负载均衡流量情况

从 网关日志/ELK/SLB 等监控平台过滤 50x 相关日志，快速定位异常接口和服务

  1. 查看所有容器状态

# 默认namespace: vika-app 
kubectl --kubeconfig  /data/vika/app/config-k8s/kubeconfig get pods -n vika-app

是否都在Running呢？

fusion-server 和room-server出现大量restart 时，是数据库出现连接不上的情况。

  1. 查看数据库性能情况

    • MySQL诊断 CPU/内存/磁盘使用率 监控：

    • MySQL10秒查询 错误日志、异常告警：

    • MySQL SQL慢查询：

Q: API 接口返回”Too many connection”

原因是mysql 连接数已用完，服务连不上mysql ，一般大规模压测时产生

现像截图：

A: 调整mysql 配置连接数参数：

[mysqld]
max_connections=1000
wait_timeout=600
interactive_timeout=600

Q: 意外kill 掉ops-manager后，无法执行怎么处理，出现如下异常

ops-manager 执行失败

ops-manager 执行失败

正确做法执行docker stop ops-manager 停止容器

A: 在确保没其它进程执行ops-manager 情况下，可通过如入方式解除锁

# 备份旧state 目录
cp -a state state_back
# 替换lockId: ef996519-a449-60a3-4c70-d5e4b7f8acc5
docker run --rm --entrypoint /bin/sh -v /data/vika/app/config-k8s:/app/terraform/local/config-k8s -v /data/vika/app/custom-config:/app/terraform/local/custom-config -v /data/vika/app/state:/app/terraform/local/state docker.vika.ltd/vikadata/vika/ops-manager:v0.20.0-alpha_build500 -c "cd terraform/local 
&& terraform force-unlock ef996519-a449-60a3-4c70-d5e4b7f8acc5 -state=state/terraform.tfstate -backup=state/terraform.tfstate.backup"

Q: 如何配置GM 管理员

登录后，通过 /api/v1/user/me 获取用户的uuid

A: 全局环境变量配置 SUPER_ADMINISTRATORS=uuid1，uuid2,uuid3…. 。重启backend-server即可

Q: 如何配置外部数据库、Redis等服务？

mysql 配置参数：

innodb_buffer_pool_size = 4096M # 建议设置为数据库服务器总内存 2/3

innodb_log_buffer_size = 2048M

max_allowed_packet = 1024M

sql_mode = NO_ENGINE_SUBSTITUTION

sort_buffer_size = 2M

max_connections=1000

explicit_defaults_for_timestamp = ON

A: 在首次安装前配置，修改环境变量使配置生效，如 POC 版 ，请修改以下配置 .env.local 文件， 如 k8s 版本配置config.yaml/config/common ,

MYSQL_HOST: "mysql"
MYSQL_USERNAME: "root"
MYSQL_PASSWORD: "xxxx"
MYSQL_DATABASE: "vikadata"

REDIS_HOST: "redis"
REDIS_PASSWORD: "xxxx"
REDIS_DB: 0

执行更新命令生效。

若是POC版，且已安装完毕，需要配置外部数据库，则修改环境变量后执行指令使其生效，指令以下：

cat .env.template .env.local > .env
docker-compose up -d

Q: 哪些表数据可以定期删除，可以优化性能

A: vika_api_usage 用于记录api调用次数，企业版本可以如下方式删除。

  1. 删除指令：

truncate table vika_api_usage

2. 通过脚本定期每天删除

#!/bin/bash


sql_clean_vika_api_usage="truncate table vika_api_usage;"
slq_count_vika_api_usage="select count(*) from vika_api_usage;"

function clean(){
  echo "clean api_useage"
  docker run --rm  mysql mysql -u'帐号' -p'密码' -e "use vikadata; $sql_clean_vika_api_usage"
}

function count(){
  echo "count api_useage"
  docker run --rm  mysql mysql -u'帐号' -p'密码' -e "use vikadata; $slq_count_vika_api_usage" >> /tmp/vika_api_useage
}


date >> /tmp/vika_api_useage
count
clean

Q: 国内执行make buildpush-webserver-op构建web-server失败,如下图:

A: 由于拉取npm 依赖包失败导致. 解决方法:国内加速构建,修改文件apitable/.yarnrc.yml,添加:

npmRegistryServer: "https://registry.npm.taobao.org"

Q: 附件无法查看和预览失败

A: 查看下面两变值是否正确,示例config.yaml

config:
  common: 
    ASSETS_URL: 'assets'                                 #存储桶名,默认是assets, 可配置
    AWS_ENDPOINT: 'http://minio.vika-datacenter:9000'    #存储桶服务地址, 可配置

Q: init-db 启动失败, 容器的java 无法执行

A: 部分系统Linux内核功能——安全计算模式(seccomp)导致,禁用默认配置即可。更多参考:https://docs.docker.com/engine/security/seccomp/

修改方法: 修改 docker-compose.yaml 配置, 在init-db和init-db-enterprise服务的配置下方添加--security-opt配置,如下

init-db:
  security_opt:
    - seccomp=unconfined
  
init-db-enterprise:
  security_opt:
    - seccomp=unconfined

重新启动: docker-compose up -d

Q: 如何指定服务的时区

A: 添加全局环境变量: TZ=Asia/Shanghai

Q: mysql 数据库的表锁释放

A: 查询占用表锁的进程, 杀掉

查询方法:

SELECT
    t1.OBJECT_SCHEMA,
     t1.OBJECT_NAME,
    t1.LOCK_TYPE,
    t1.LOCK_STATUS,
    t2.PROCESSLIST_ID,
    t2.PROCESSLIST_USER,
    t2.PROCESSLIST_HOST,
    t2.PROCESSLIST_DB,
    t2.PROCESSLIST_COMMAND,
    t2.PROCESSLIST_STATE,
    t2.PROCESSLIST_INFO
FROM
    `performance_schema`.metadata_locks t1,
    `performance_schema`.threads t2
WHERE
    t1.owner_thread_id = t2.thread_id
AND t1.OBJECT_SCHEMA = '<库名>'
AND t1.OBJECT_NAME = '<表名>'

获取持有或者等待metadata锁的会话才会被记录

结果中LOCK_STATUS字段表示连接对于matadata锁的持有状态，GRANTED表示持有，PENDING表示等待。很容易可以看出来1075956038会话持有了锁，而其它会话正在等待这个锁。通过kill 1075956038语句，或者让1075956038提交回滚都能解决这个问题。

Q: 如何配置工作台表格读写分离

A: 在k8s 集群版本, 将room-server 分拆为：room-server与nest-rest-server , nest-rest-server专门用于处理 /nest 请求(表读操作) , 表加载慢时也不影响表格内协同操作，功能如下

  • nest-rest-server: 表格数据加载, 如dataPack

  • room-server: 表格op协同

    修改config.yaml 开启,配置如下

    container:
  nest_rest_server:
     replicas: 2 
common:
  custom:
     has_nest_rest_server: true   #ops-manager v1.1.0+ 版本支持

Q：外部网关代理到维格

协同采用websocket 协议, 代理时需支持该协议

A: 采用TCP 4层协议代理或开启websocket 代理, 例如nginx 配置:


      map $http_upgrade $connection_upgrade {
            default upgrade;
            ''  close;
        }  

       server {
             
             charset utf-8;

             location / {
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_set_header X-Nginx-Proxy true;
                proxy_set_header Host $http_host;
                proxy_set_header X-Original-URI $request_uri;
                proxy_http_version 1.1;
                proxy_pass  http://维格服务器地址:端口;
            }
            
             location /_next/ {
                proxy_set_header Host $http_host;
                proxy_set_header X-Original-URI $request_uri;
                proxy_pass  http://维格服务器地址:端口;
                
            }
      }

Q：redis无法正常重启如何处理？

A：docker ps排查后，发现redis没有正常重启的情况下，进入vikadata目录 - 关闭所有服务 - 清空redis数据 - 重启所有服务

cd /data/vikadata
docker-compose down
rm -rf .data/redis/
docker-compose up -d

Q: poc 版本gateway 启动失败问题

报错: docker: Error response from daemon: driver failed programming external connectivity on endpoint vikadata-gateway-1(ea5aa3ef1f80513ee314d01f46c3bda46f3847b03fda3051ce73500bcea58ba0): Error starting userland

proxy: listen tcp [::]:80: bind: address already in use

实际上 80 端口未被占用,修改其它端口也会失败

A: 宿主机缺少ipv6目录及文件，重新生成ipv6相关文件即可（同时可禁用ipv6）

修改/etc/sysctl.conf : 

net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1

重启服务:

systemctl restart docker
docker-compose up -d

Q: 如何在数据库更换主管理员？

由于私有化版验证码无法使用的特殊情况下，可通过修改数据库表的方式，手动更换空间站主管理员，如：

新管理员账号： abc@vikatest.com , 空间站id: spc1111

A. 设置空间站成员角色

查询新管理员的memberId

select * from vika_unit_member where space_id='spc1111' and email='abc@vikatest.com' limit 5;

如 member id 为 1111111

#查询旧的管理员 select * from vika_unit_member where space_id='spc1111' and is_admin=1;

取消旧空间站管理员

update vika_unit_member set is_admin=0 where space_id='spc1111' and is_admin=1;

#设置成员为管理员角色 
update vika_unit_member set is_admin=1 where space_id='spc1111' and email='abc@vikatest.com'

B. 设置管空间站管理员

member_id 11111 从上一步获取

update vika_space set owner=1111111 where space_id='spc1111';

操作完成.

打开空间站驾驶舱可看到管理员已更新, 新主管理员过1-2小时就能生效.

Q: 如何在数据库绑定邮箱

由于私有化版验证码无法使用的特殊情况下，可通过修改数据库表的方式. 操作有风险

#如邮箱 abc@vikatest.com , 用户ID: 1111
#用户ID查看：{host}/api/v1/user/me 中data取 "uuid": "111"

update vika_user set email="abc@vikatest.com" where uuid='111'

Q: 如何在数据库里注销账号

如果是vika本地安装的mysql数据库，进入服务器，按下面的步骤操作：

1、进入mysql 数据库的容器
docker exec -it vikadata-mysql-1 bash

2、登录mysql 数据库（默认账号密码请联系vika官方获取）
 mysql -u'帐号' -p'密码'

3、进入vika数据库
use vikadata;

4、注销账号
update vika_user set is_deleted=1 where email='xxxx';

Q：推送后的邮件里，点击「查看记录」等按钮时出现错误的URL如何解决？

推送的邮件如下图，点击「查看记录」后，跳转到一个错误URL

解决方法：

在backend-server里配置 「server_domain」的变量，设置好自定义域名地址，重启backend-server服务，重新推送的邮件会自动跳转到正确的地址

比如： SERVER_DOMAIN=https://apitable.com ，重启backend-server即可

Q：如何开放验证码登录/注册？

解决方法：

配置环境变量 LOGIN_DEFAULT_VERIFY_TYPE='password_login,identify_code_login' 重启 web-server服务即可

Q：如何在数据库更新API token？

解决方法：

1.获取当前token：点击个人设置-开发者配置-复制api令牌"Axxxxxxxx"；

2.登录数据库，执行sql

DELETE FROM vika_developer WHERE api_key="Axxxxxxxx";

3.页面重新生成一个新的令牌即可。

Q: 有创建空间站、创建文件夹等API接口？

答: 私有化版本支持更全面API, 支持创建空间站 ,节点和目录等, 见 《API接口对接文档》

Q: 维格表页面（URL地址）是否可以内嵌到其他系统，通过iframe形式实现?

答: 维格表具备强大的嵌入功能，使您能够实现第三方应用和系统之间的无缝数据连接，从而打造更加全面的场景解决方案。

嵌入功能说明: https://developers.vika.cn/api/create-embedlinks

案例: https://help.vika.cn/docs/customer-story/case-embed

1.站点必须开启https

2.配置embed 相关环境变量后,重新登录生效:

COOKIES_SECURE='true'
COOKIES_SAME_SITE=None

重启backend-server.

POC 版本变量配置方法

k8s版本配置方法

Q: 维格现在使用mysql数据库，是否支持其他类型数据库，比如oracle、sqlserver

答: 维格表只支持mysql8.0 和完全兼容mysql数据库(TaurusDB V2.0-集群版),不支持其它数据库。

Q: 图片裁剪性能比较慢,有什么优化方法吗?

答: 集群版本可以扩容imageproxy-server 服务,并且设置剪裁缓存到S3。

以内置 minio 为例,增加缓存方法:

  1. 在 minio 创建存储桶: imageproxy

    mc mb minio/imageproxy

  2. 在config.yaml配置s3 缓存

     config:
  custom:
    imageproxy_server:
      AWS_ACCESS_KEY_ID: '{替换access_key}'
      AWS_SECRET_KEY: '{替换access_scret}'
      IMAGEPROXY_CACHE: 's3://fake-region/imageproxy/cache?endpoint=minio.vika-datacenter:9000&disableSSL=1&s3ForcePathStyle=1'

Q: 维格表一直显示加载中图标

答: 主要网络中有安全设备误拦截了前端js 资源, 需放开 /_next 路径

注: 路径里 [...] 字符触发了waf 防火墙规则误判, 被拦截了. 它是在 react js 是个动态路由的语法